diff --git a/Containers/Docker/Docker Compose/Material MkDocs.md b/Containers/Docker/Docker Compose/Material MkDocs.md index c66b1b6..e0f8c8e 100644 --- a/Containers/Docker/Docker Compose/Material MkDocs.md +++ b/Containers/Docker/Docker Compose/Material MkDocs.md @@ -3,6 +3,7 @@ !!! note This is best deployed in tandem with the [Git Repo Updater](https://docs.bunny-lab.io/Containers/Docker/Docker%20Compose/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/Containers/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/Containers/Portainer/Deploy%20Portainer/). +## Deploy Material MKDocs ```jsx title="docker-compose.yml" version: '3' @@ -27,4 +28,144 @@ networks: ```jsx title=".env" N/A -``` \ No newline at end of file +``` + +## Config Example +When you deploy MKDocs, you will need to give it a configuration to tell MKDocs how to structure itself. The configuration below is what I used in my deployment. This file is one folder level higher than the `/docs` folder that holds the documentation of the website. +```jsx title="mkdocs.yml" +# Project information +site_name: Bunny Lab Documentation +site_url: https://docs.bunny-lab.io +site_author: Nicole Rappe +site_description: >- + Bunny Lab Server, Script, and Container Documentation + +# Configuration +theme: + name: material + custom_dir: material/overrides + features: + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + - content.tabs.link + - content.tooltips +# - header.autohide + - navigation.expand +# - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - navigation.prune + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow +# - toc.integrate ## If this is enabled, the TOC will appear on the left navigation menu. + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/link + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: purple + accent: purple + toggle: + icon: material/toggle-switch + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: purple + toggle: + icon: material/toggle-switch-off + name: Switch to system preference + font: + text: Roboto + code: Roboto Mono + favicon: assets/favicon.png + icon: + logo: logo + +# Plugins +plugins: + - search: + separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' + - minify: + minify_html: true + +# Hooks +hooks: + - material/overrides/hooks/shortcodes.py + - material/overrides/hooks/translations.py + +# Additional configuration +extra: + status: + new: Recently added + deprecated: Deprecated + +# Extensions +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + normalize_issue_symbols: true + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets: + auto_append: + - includes/mkdocs.md + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + combine_header_slug: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde +``` + +## 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