feat: MkDocs config improvements (#37)

* chore: add site/ to .gitignore

* feat: add instant prefetch and progress bar navigation

* feat: add syntax highlighting for code blocks

Add pymdownx.highlight with anchor line numbers and
pymdownx.inlinehilite for inline code highlighting.

* fix: use standard permalink for table of contents

* feat: add mkdocs-minify-plugin for smaller output

Minifies HTML, JS, and CSS in built output for faster page loads.
Moves search plugin before glightbox for correct load order.

* ci: enable strict mode for mkdocs build

---------

Co-authored-by: bakerboy448 <bakerboy448@users.noreply.github.com>

Author: bakerboy448

.github/workflows/build.yml

@@ -26,4 +26,4 @@ jobs:
             ${{ runner.os }}-pip-
       - run: |
           python3 -m pip install -r requirements.txt
-          mkdocs build
+          mkdocs build --strict

.github/workflows/deploy.yml

@@ -40,7 +40,7 @@ jobs:
         run: python3 -m pip install -r ./requirements.txt
 
       - name: Build Docs
-        run: mkdocs build
+        run: mkdocs build --strict
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4

.gitignore

@@ -1 +1,2 @@
 .venv
+site/

mkdocs.yml

@@ -107,6 +107,8 @@ theme:
     - navigation.top
     - navigation.tracking
     - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
     - toc.follow
     - search.suggest
     - search.highlight
@@ -130,6 +132,7 @@ extra_css:
   - stylesheets/github-permalink-style.css
 
 plugins:
+  - search
   - glightbox:
       touchNavigation: true
       loop: false
@@ -140,7 +143,12 @@ plugins:
       draggable: true
       auto_caption: false
       caption_position: bottom
-  - search
+  - minify:
+      minify_html: true
+      minify_js: true
+      minify_css: true
+      htmlmin_opts:
+        remove_comments: true
 
 markdown_extensions:
   - attr_list
@@ -150,10 +158,13 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
   - tables
   - pymdownx.tabbed:
       alternate_style: true
   - md_in_html
   - toc:
       toc_depth: 4
-      permalink: ''
+      permalink: true

requirements.txt

@@ -2,3 +2,4 @@ mkdocs~=1.6.0
 mkdocs-material~=9.7.1
 mkdocs-material-extensions~=1.3.0
 mkdocs-glightbox~=0.5.0
+mkdocs-minify-plugin~=0.8.0