Update Servers/Containerization/Docker/Compose/Material MkDocs.md
All checks were successful
GitOps Automatic Deployment / GitOps Automatic Deployment (push) Successful in 7s
All checks were successful
GitOps Automatic Deployment / GitOps Automatic Deployment (push) Successful in 7s
This commit is contained in:
@@ -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:
|
||||
@@ -195,3 +175,6 @@ 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`.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user