Update Servers/Containerization/Docker/Compose/Material MkDocs.md
All checks were successful
GitOps Automatic Deployment / GitOps Automatic Deployment (push) Successful in 7s

This commit is contained in:
2025-12-13 15:13:20 -07:00
parent 89e8d41528
commit 0c99cb63bc

View File

@@ -1,28 +1,5 @@
**Purpose**: Documentation that simply works. Write your documentation in Markdown and create a professional static site for your Open Source or commercial project in minutes searchable, customizable, more than 60 languages, for all devices.
!!! note
This is best deployed in tandem with the [Git Repo Updater](https://docs.bunny-lab.io/Docker%20%26%20Kubernetes/Docker/Custom%20Containers/Git%20Repo%20Updater/) container in its own stack. Utilizing this will allow you to push commits to a repository to immediately (within 5 seconds) push changes into MKDocs without needing SSH/Portainer access to the server hosting MKDocs. If you don't have a GitHub account, consider deploying a [Gitea](https://docs.bunny-lab.io/Docker%20%26%20Kubernetes/Docker/Docker%20Compose/Gitea/) container to host your own code repository! This all assumes you have already deployed [Docker and Portainer](https://docs.bunny-lab.io/Docker%20%26%20Kubernetes/Servers/Docker/Portainer/).
## Documentation / Pull Sequence
``` mermaid
sequenceDiagram
participant Gitea
participant Git_Repo_Updater as Git-Repo-Updater
participant MkDocs
participant NTFY
loop Every 5 seconds
Git_Repo_Updater->>Gitea: Check for changes in repository
alt Changes Detected
Gitea->>Git_Repo_Updater: Notify change
Git_Repo_Updater->>NTFY: Send change notification
Git_Repo_Updater->>Gitea: Download data from repository
Git_Repo_Updater->>MkDocs: Copy data to MkDocs
MkDocs->>MkDocs: Reload and render webpages
end
end
```
## Deploy Material MKDocs
```yaml title="docker-compose.yml"
version: '3'
@@ -77,14 +54,15 @@ theme:
- content.tabs.link
- content.tooltips
# - header.autohide
- navigation.expand
# - navigation.expand
# - navigation.footer
- navigation.indexes
- navigation.instant
- navigation.instant.prefetch
- navigation.instant.progress
- navigation.prune
- navigation.sections
- navigation.path
# - navigation.sections
- navigation.tabs
- navigation.tabs.sticky
- navigation.top
@@ -126,6 +104,8 @@ plugins:
separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
- minify:
minify_html: true
- blog
- tags
# Hooks
hooks:
@@ -194,4 +174,7 @@ markdown_extensions:
```
## Cleaning up
When the server is deployed, it will come with a bunch of unnecessary documentation that tells you how to use it. You will want to go into the `/docs` folder, and delete everything except `assets/favicon.png`, `schema.json`, and `/schema`. These files are necessary to allow MKDocs to automatically detect and structure the documentation based on the file folder structure under `/docs`.
When the server is deployed, it will come with a bunch of unnecessary documentation that tells you how to use it. You will want to go into the `/docs` folder, and delete everything except `assets/favicon.png`, `schema.json`, and `/schema`. These files are necessary to allow MKDocs to automatically detect and structure the documentation based on the file folder structure under `/docs`.
## Hotloading Bug Workaround
There is a [known bug](https://github.com/mkdocs/mkdocs/issues/4055) with the most recent version of Material MKDocs (as of writing) that causes it to not hotload changes immediately. This can be fixed by entering a shell in the docker container using `/bin/sh` then running the following command to downgrade the python "click" package: `pip install click==8.2.1`. After running the command, restart the container and hotloaded changes should start working again. You will have to run this command every time you re-deploy Material MKDocs until the issue is resolved officially.