starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[Enhancement]: consolidate docs with in this repository #2750

New Issue
Open
opened 2026-04-25 00:10:11 +02:00 by adam · 3 comments
adam commented 2026-04-25 00:10:11 +02:00
Owner
Copy Link
Copy Source

Originally created by @Torstein-Eide on GitHub (May 3, 2025).

Type of Enhancement

Documentation

Describe the Feature/Enhancement

Currently the documentations is split between:

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

Originally created by @Torstein-Eide on GitHub (May 3, 2025). ### Type of Enhancement Documentation ### Describe the Feature/Enhancement ## Currently the documentations is split between: - [audiobookshelf/audiobookshelf-web](https://github.com/audiobookshelf/audiobookshelf-web) - [/readme.md](https://github.com/advplyr/audiobookshelf/blob/master/readme.md) - [docs/README.md](https://github.com/advplyr/audiobookshelf/blob/master/docs/README.md) - [server/migrations/readme.md](https://github.com/advplyr/audiobookshelf/blob/master/server/migrations/readme.md) ## move the `/content` From [audiobookshelf-web](https://github.com/audiobookshelf/audiobookshelf-web/tree/master/content) move the `/content` to this repo. This is simlare to other projects like [librenms](https://github.com/librenms/librenms) and [immich](https://github.com/immich-app/immich/tree/main) ### 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
adam added the enhancement label 2026-04-25 00:10:11 +02:00
adam commented 2026-04-25 00:10:12 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (May 5, 2025):

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 https://github.com/audiobookshelf/audiobookshelf-web/pull/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 https://github.com/audiobookshelf/audiobookshelf-web/pull/133#issuecomment-2849089325. 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.
    existing screenshot
  • 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.
    image
@nichwall commented on GitHub (May 5, 2025): 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 https://github.com/audiobookshelf/audiobookshelf-web/pull/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 https://github.com/audiobookshelf/audiobookshelf-web/pull/133#issuecomment-2849089325. 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. ![existing screenshot](https://github.com/user-attachments/assets/aff37c85-136b-4505-8d77-a63a58336038) - 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. ![image](https://github.com/user-attachments/assets/fa4bba8e-bde6-47d5-adb7-683d43c2b342)
adam commented 2026-04-25 00:10:12 +02:00
Author
Owner
Copy Link
Copy Source

@Torstein-Eide commented on GitHub (May 5, 2025):

  • 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.

@Torstein-Eide commented on GitHub (May 5, 2025): > * 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](docs.audiobookshelf.org) or [www.audiobookshelf.org/docs](www.audiobookshelf.org/docs), and the front page kept at [www.audiobookshelf.org](www.audiobookshelf.org). There is also options for Customized in [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/setup/). > * 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](https://github.com/immich-app/immich/releases/tag/v1.132.0) does it, releases send mail for people using the "watch" function. There is also "Documentation" that is more long-term, more structured.
adam commented 2026-04-25 00:10:12 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (May 5, 2025):

  • 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

@nichwall commented on GitHub (May 5, 2025): > > * 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](docs.audiobookshelf.org) or [www.audiobookshelf.org/docs](www.audiobookshelf.org/docs), and the front page kept at [www.audiobookshelf.org](www.audiobookshelf.org). > > There is also options for Customized in [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/setup/). > 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](https://github.com/immich-app/immich/releases/tag/v1.132.0) 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
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#2750
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?