Material mkdocs rewrite

[nichwall]

This PR is an attempt to switch to Material for Mkdocs for the documentation, as briefly discussed in advplyr/audiobookshelf#4257 and #133 (comment).

This PR is incomplete, and is mostly as a test to see if this can be done. This should not be merged, it will break the website due to using a different build process.

Setting up the environment

To setup the environment, you need to have Material for Mkdocs installed. I have added .venv to the gitignore so this can be done within the project.

python3 -m venv .venv        # Create the virtual environment
source .venv/bin/activate    # Use this when returning to the project to use the virtual environment with the
pip3 install mkdocs-material # Install the libraries

Once you are using the virtual environment, you can run the server with mkdocs serve, which will run on port 8000 by default.

To deploy with Netlify, use these docs. I have not gone through all of these steps for actually publishing from local.

Navigation

The basic site structure has everything under docs/. This includes all of the markdown files and static assets. I have moved the documentation, guides, and FAQ, and mostly recreated the home page (though I will need help with that).

An example of one of the guides is shown below.

Custom Page

Current homepage implementation (missing center image, shelves, font change). This does reduce the homepage size by quite a bit (from 3.8 MB down to 2 MB) due to being done in raw HTML instead of a statically generated nuxt page with multiple javascript bundles. This page can be found under docs/overrides/main.html. We do still need docs/index.md to exist for the homepage to load.

Remaining Tasks

• Finish converting homepage
• Convert documentation pages to be fully markdown, update for rendering
• Migrate showcase page
• Migrate Privacy policy page
• Update color scheme and fonts
• Update normal page HTML to have the background gradient?
• Fix navigation tabs https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs
• Fix section index pages https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages
• Add redirects from old pages (in markdown header)

[netlify]

✅ Deploy Preview for audiobookshelf ready!

Name	Link
🔨 Latest commit	0275ab8
🔍 Latest deploy log	https://app.netlify.com/projects/audiobookshelf/deploys/6840ba77965d74000840e611
😎 Deploy Preview	https://deploy-preview-136--audiobookshelf.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[advplyr]

Nice, I was able to run it easily. I think this will work.

The navigation is clunky for me. Slow full-page reloads. Are you getting that also?

It doesn't look like mkdocs is in active development anymore. Last update that wasn't docs was 9 months ago. That could be a concern

[nichwall]

I did not notice slow navigation or full page reloads. You can configure the website in the mkdocs.yaml to preload pages and work more like a SPA (among many other configuration options, I have not gone through all of them yet).

[nichwall]

Here is the navigation config if you want to try faster navigation.

https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=navigation#instant-loading