diff --git a/Servers/Containerization/Docker/Compose/Material MkDocs.md b/Servers/Containerization/Docker/Compose/Material MkDocs.md index 072d02b..a648555 100644 --- a/Servers/Containerization/Docker/Compose/Material MkDocs.md +++ b/Servers/Containerization/Docker/Compose/Material MkDocs.md @@ -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`. \ No newline at end of file +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. \ No newline at end of file