[Enhancement]: consolidate docs with in this repository

[Torstein-Eide]

Type of Enhancement

Documentation

Describe the Feature/Enhancement

Currently the documentations is split between:

• audiobookshelf/audiobookshelf-web
• /readme.md
• docs/README.md
• server/migrations/readme.md

move the /content

From audiobookshelf-web move the /content to this repo.

This is simlare to other projects like librenms and immich

Why would this be helpful?

The goal is to consolidate all user-facing documentation, guides, and setup instructions into the Same Repository. This provides several benefits:

• Single Source of Truth: Users will have one place to look for all documentation.
• Easier Maintenance: Pull request can include documentation updates.
• Improved Discoverability: Centralizing docs makes easy to find the docs, align ithe
• Possibility to read the docs locally (pun intended 😃 ).

Future Implementation (Screenshot)

NA

Audiobookshelf Server Version

NA

Current Implementation (Screenshot)

NA

[nichwall]

I agree that documentation organization should be addressed, but I do not think everything should be merged into the server repository and instead remain in the website repository (some conversation already in audiobookshelf/audiobookshelf-web#133). But, the fact that this conversation is already over 3 issues/PRs is a good representation of it needing to be consolidated. (Some conversation is already in the PR, but I think this issue is a better place to have the conversation?)

For some background, the website (hosted at audiobookshelf.org and located in https://github.com/audiobookshelf/audiobookshelf-web originally included only the "Documentation", "User Guides", "How to Support", and "Showcase" sections. The "FAQ" was added later. Over time, the distinction between "Documentation" (which is project-generated) and "User Guides" (community-contributed help for other users) has become increasingly unclear as more people have contributed to the documentation. Also worth noting: markdown file support was added to the documentation system later on, so not everything transitioned cleanly as you mentioned, but markdown has been supported for a while so that can probably be cleaned up.

I don't know how important the existing website layout is to the project branding. I think migrating to a new documentation framework is be worth the time, even though a decent amount of time has been invested in the current documentation framework. The most important part is ensuring the documentation is consistent, easy to navigate, easy to update and maintain, and easy for users to contribute to.

I agree that the Migrations and OpenAPI Readmes could be easily added to the website documentation in a contributing section. Migrating to a new framework would also make adding new "sections" easier.

If we were to change to a new documentation framework, I do like Material for MkDocs as you mentioned in audiobookshelf/audiobookshelf-web#133 (comment). It looks pretty simple to manage and set up. My main comments on it (without having done a deep dive or much research beyond this initial response):

• Almost every page will be easy to transfer over due to mostly being done in markdown.
• Can we keep the main page of the website looking the same? I specifically mean the books in the background and the blurred diagonal, not sure how "custom" a page can be.
  
• I think the "blog" plugin could be handy. I have tried to do something like that with the faq_and_annoucements channel in Discord (current implementation below). This channel is mainly to redirect people from Discord to the website for the common questions so we did not need to mirror everything in Discord, but people tend to not check the website or GitHub for common questions so they were added there.
  

[Torstein-Eide]

• Can we keep the main page of the website looking the same? I specifically mean the books in the background and the blurred diagonal, not sure how "custom" a page can be.

Sure. Docs can be at docs.audiobookshelf.org or www.audiobookshelf.org/docs, and the front page kept at www.audiobookshelf.org.

There is also options for Customized in Material for MkDocs.

• I think the "blog" plugin could be handy. I have tried to do something like that with the faq_and_annoucements channel in Discord (current implementation below).

I am unsure of "blog" is the correct thing to use. I my mind there is "news" this can be achieve via Github release, I personally like the way immich does it, releases send mail for people using the "watch" function. There is also "Documentation" that is more long-term, more structured.

[nichwall]

• Can we keep the main page of the website looking the same? I specifically mean the books in the background and the blurred diagonal, not sure how "custom" a page can be.

Sure. Docs can be at docs.audiobookshelf.org or www.audiobookshelf.org/docs, and the front page kept at www.audiobookshelf.org.

There is also options for Customized in Material for MkDocs.

Thanks, I briefly looked at the customized pages, looks like we would just need to make a new page template for the home/landing page, but that should be all we need to do.

I am unsure of "blog" is the correct thing to use. I my mind there is "news" this can be achieve via Github release, I personally like the way immich does it, releases send mail for people using the "watch" function. There is also "Documentation" that is more long-term, more structured.

Yeah, I agree the release notes and structured documentation would be the best place for it. We currently redirect people to the release notes or the FAQ on the website, I'm just speaking from experience because a lot of people don't seem to read the release notes and just go directly to Discord.

The blog functionality probably isn't the best way either, just a thought.

https://github.com/advplyr/audiobookshelf/releases