Skip to content

MkDocs

Simplified Documentation with Markdown

docs diagram

MkDocs stands as a versatile and user-friendly documentation tool that transforms simple Markdown files into elegant and responsive websites. Developed with simplicity and ease of use in mind, MkDocs empowers individuals and teams to create professional-looking documentation without the need for complex configurations or technical expertise.

Key Features

  • Markdown-Based: MkDocs leverages the simplicity of Markdown, allowing users to focus on content creation without the need for intricate markup or coding.

  • Built-In Theming: Choose from a variety of built-in themes to give your documentation a polished and professional appearance effortlessly.

  • Customization: Tailor your documentation site with custom themes, plugins, and configurations to match your branding and requirements.

  • Responsive Design: MkDocs generates documentation with a responsive design, ensuring an optimal reading experience on various devices.

Getting Started

Embark on your documentation journey with MkDocs by following the straightforward setup and configuration steps outlined in the official documentation. Whether you're a developer, writer, or team lead, MkDocs simplifies the process of creating and maintaining documentation.

Community and Support

Connect with the MkDocs community on GitHub to engage in discussions, report issues, and stay informed about updates. The collaborative nature of MkDocs ensures a supportive environment for users at all levels of expertise.

Experience the power of streamlined documentation creation with MkDocs, where Markdown meets elegance.

Volumes

/nfs-nas-swarm/data/docs

Deployment

First you should create a config file "mkdocs.yml" on the shared volume.

nano /nfs-nas-swarm/config/docs/mkdocs.yml
theme:
  name: 'material'

you can grab a default config file by deploying a temp container

docker run --rm -it -p 8000:8000 -v /nfs-nas-swarm/config/docs:/docs squidfunk/mkdocs-material 

Docker swarm file

version: '3.3'
services:
  docs:
    image: keinstien/mkdocs-material:9.5.26
    environment:
      FAST_MODE: 'true'
      LIVE_RELOAD_SUPPORT: 'true'
      PGID: '0'
      PUID: '0'
      TZ: Europe/Amsterdam
      # dev-addr: docs.vnerd.nl
    volumes:
     - /swarm/config/docs:/docs
     - /swarm/github-repos/portainer-compose:/docs/github-repos/portainer-compose
     - /swarm/config:/docs/configs
    networks:
     - internal
     - traefik-public
    logging:
      driver: json-file
    deploy:
      # replicas: 0
      labels:
        # sablier.enable: 'true'
        traefik.http.routers.docs-https.tls: 'true'
        traefik.http.routers.docs-https.tls.certresolver: le
        traefik.http.routers.docs-http.entrypoints: http
        traefik.http.services.docs.loadbalancer.server.port: '8000'
        # traefik.http.routers.docs-https.middlewares: docs-sablier@file
        # traefik.http.routers.docs-https.middlewares: 500error@file
        traefik.http.routers.docs-https.entrypoints: https
        traefik.http.routers.docs-https.rule: Host(`docs.vnerd.nl`)
        # sablier.group: docs
        traefik.constraint-label: traefik-public
        # traefik.docker.lbswarm: 'true'
        traefik.docker.network: traefik-public
        traefik.enable: 'true'
        traefik.http.routers.docs-http.middlewares: https-redirect
        traefik.http.routers.docs-http.rule: Host(`docs.vnerd.nl`)
      placement:
        constraints:
         - node.labels.Arch!=i686
         - node.labels.worker==enabled
networks:
  internal:
    driver: overlay
  traefik-public:
    external: true

Notes

Comments