vNerd Docs

This repository contains the source for the vNerd homelab documentation site served at vNerd docs website. The site is built with MkDocs Material and documents Docker Swarm stacks, infrastructure components, automation workflows and the documentation toolchain used by the owner.

Quick summary

• Tech: MkDocs (Material theme), Markdown content, a few helper scripts for diagram generation.
• Purpose: Human-friendly documentation for a home Docker Swarm infrastructure and supporting services.
• Live site: https://docs.vnerd.nl/ (builds from the contents of this repository)

Layout / important folders

• docs/ - All website content. Organized into sections such as Docker Swarm Stacks, Infrastructure, Special Services, and assets for images/diagrams.
• docs/assets/diagrams/temp/ - Diagram generation helper scripts and temporary files.
• overrides/ - Theme overrides and template partials (for example, comments integration).
• github-repos/portainer-compose - External repository used to generate embed content and stack diagrams (kept as a submodule-like reference in the doc flow).
• .github/ - GitHub Actions and repository guidance; plus developer instructions used by helpers.

Key patterns and conventions

• Docker stack documentation pages follow a consistent format: short introduction, diagram, key features, volumes, deployment steps, and the YAML configuration embedded from the external portainer-compose repo.
• External content may be embedded using the mkdocs-embed-external-markdown plugin with the --8<-- include syntax.
• Diagrams are generated by a script that uses pmsipilot/docker-compose-viz to turn compose files into architecture diagrams.

Run the docs locally (quick)

You can run the site locally with the custom MkDocs image used by this project. From the repository root:

# Run the site using the project's MkDocs image
docker run --rm -it -p 8000:8000 -v $(pwd):/docs keinstien/mkdocs-material:9.5.26

Then open http://localhost:8000 in your browser.

If you prefer to use a local Python environment, install dependencies declared in mkdocs.yml (plugins, theme) and run mkdocs serve.

Generate / update diagrams

Diagrams for Docker stacks are generated by the script located at:

./swarm/config/docs/docs/assets/diagrams/temp/generate_script.sh

That script runs pmsipilot/docker-compose-viz against files in (or generated from) the portainer-compose repository to produce image files under docs/assets/diagrams/.

Content sources and dynamic embedding

This project pulls configuration and some content from the external portainer-compose repository. The documentation uses automated includes and sometimes auto-generated diagrams to keep documentation synchronized with the actual stack files.

Practical notes & housekeeping

• This repository previously used paths under /nfs-nas-swarm in examples and fstab snippets. Those references were consolidated to /swarm to simplify paths across the docs. If you depend on a different mountpoint, review any scripts or runtime systems before applying changes.
• After editing documentation that references host paths or fstab entries (for example docs/Infrastructure/Proxmox/create_node.md), double-check deployed machines and automation scripts to avoid accidental breakage.

Validation / Quality gates

• Before merging PRs, run a local mkdocs build to ensure the site generates without fatal errors.
• Optionally run link-checking or a small CI step (GitHub Actions) to validate internal links and basic markup.

Where to find more

• Template and conventions are documented in docs/Docker Swarm Stacks/index.md and .github/copilot-instructions.md contains project-specific guidance for contributors and the docs generation workflow.