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.
|
**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
|
## Deploy Material MKDocs
|
||||||
```yaml title="docker-compose.yml"
|
```yaml title="docker-compose.yml"
|
||||||
version: '3'
|
version: '3'
|
||||||
@@ -77,14 +54,15 @@ theme:
|
|||||||
- content.tabs.link
|
- content.tabs.link
|
||||||
- content.tooltips
|
- content.tooltips
|
||||||
# - header.autohide
|
# - header.autohide
|
||||||
- navigation.expand
|
# - navigation.expand
|
||||||
# - navigation.footer
|
# - navigation.footer
|
||||||
- navigation.indexes
|
- navigation.indexes
|
||||||
- navigation.instant
|
- navigation.instant
|
||||||
- navigation.instant.prefetch
|
- navigation.instant.prefetch
|
||||||
- navigation.instant.progress
|
- navigation.instant.progress
|
||||||
- navigation.prune
|
- navigation.prune
|
||||||
- navigation.sections
|
- navigation.path
|
||||||
|
# - navigation.sections
|
||||||
- navigation.tabs
|
- navigation.tabs
|
||||||
- navigation.tabs.sticky
|
- navigation.tabs.sticky
|
||||||
- navigation.top
|
- navigation.top
|
||||||
@@ -126,6 +104,8 @@ plugins:
|
|||||||
separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
|
separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
|
||||||
- minify:
|
- minify:
|
||||||
minify_html: true
|
minify_html: true
|
||||||
|
- blog
|
||||||
|
- tags
|
||||||
|
|
||||||
# Hooks
|
# Hooks
|
||||||
hooks:
|
hooks:
|
||||||
@@ -195,3 +175,6 @@ markdown_extensions:
|
|||||||
|
|
||||||
## Cleaning up
|
## 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.
|
||||||
Reference in New Issue
Block a user