feat: add MkDocs documentation site with GitHub Pages deployment

Adds a searchable, navigable documentation site built with MkDocs
and the Material theme. The site includes all 159 role READMEs,
playbook documentation, and reference material.

Author: markuslf

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: 'Deploy Documentation'
+
+on:
+  push:
+    branches:
+      - 'main'
+
+permissions:
+  contents: 'read'
+  pages: 'write'
+  id-token: 'write'
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Checkout repository'
+        uses: 'actions/checkout@v6'
+
+      - name: 'Set up Python'
+        uses: 'actions/setup-python@v6'
+        with:
+          python-version: '3.12'
+
+      - name: 'Install dependencies'
+        run: 'pip install mkdocs mkdocs-material'
+
+      - name: 'Generate docs structure'
+        run: 'python3 tools/build-docs'
+
+      - name: 'Build documentation'
+        run: 'mkdocs build --strict'
+
+      - name: 'Upload Pages artifact'
+        uses: 'actions/upload-pages-artifact@v4'
+        with:
+          path: 'site'
+
+  deploy:
+    needs: 'build'
+    runs-on: 'ubuntu-latest'
+    environment:
+      name: 'github-pages'
+      url: '${{ steps.deployment.outputs.page_url }}'
+    steps:
+      - name: 'Deploy to GitHub Pages'
+        id: 'deployment'
+        uses: 'actions/deploy-pages@v5'

.gitignore

@@ -8,3 +8,15 @@ playbooks/test.yml
 roles/test
 context/
 particle/.vagrant
+
+# mkdocs documentation
+/docs/CHANGELOG.md
+/docs/CODE_OF_CONDUCT.md
+/docs/compatibility.md
+/docs/contributing.md
+/docs/playbooks.md
+/docs/roles/
+/docs/security.md
+/docs/stigs.md
+/mkdocs.yml
+/site

CHANGELOG.md

@@ -30,6 +30,7 @@ tbd
 
 ### Added
 
+* Add MkDocs-based documentation site, deployed automatically to GitHub Pages via `tools/build-docs` and a GitHub Actions workflow
 * **CONTRIBUTING**: Document semantic parameter ordering for Ansible modules
 * **playbooks**: Add `example.yml` and `setup_example.yml` playbooks as development references
 * **role:example**: Add complete example role with defaults, handlers, tasks, templates, and vars as a reference for consistent role development

README.md

@@ -406,6 +406,8 @@ See `ansible-doc -t lookup linuxfabrik.lfops.bitwarden_item` for all options.
 
 ## Documentation
 
+Full documentation is available at [linuxfabrik.github.io/lfops](https://linuxfabrik.github.io/lfops/). It is automatically built and deployed on every push to `main`.
+
 * **Ansible Roles**: Each role has its own README file in [`roles/<role_name>/`](roles/).
 * **Ansible Plugins**: Available through `ansible-doc`. For example: `ansible-doc linuxfabrik.lfops.gpg_key`.
 * **Changelog**: [CHANGELOG.md](CHANGELOG.md)

docs/index.md

@@ -0,0 +1,28 @@
+# Linuxfabrik LFOps
+
+Ansible Collection of roles, playbooks and plugins for Linux-based cloud infrastructure. Covers OS hardening, MariaDB, Icinga2, Nextcloud, FreeIPA, KVM and more.
+
+Made by [Linuxfabrik](https://www.linuxfabrik.ch).
+
+
+## Overview
+
+LFOps is a comprehensive Ansible Collection providing 145+ playbooks and 160+ roles to bootstrap and manage Linux-based IT infrastructures. It covers the full server lifecycle from initial provisioning and hardening to application deployment, monitoring, and automated backups. LFOps supports RHEL 8/9/10, Debian, and Ubuntu.
+
+
+## Quick Start
+
+1. Install via Galaxy: `ansible-galaxy collection install linuxfabrik.lfops`
+2. Check [Compatibility](compatibility.md) for supported platforms
+3. Browse [Roles](roles/acme_sh.md) and [Playbooks](playbooks.md)
+4. See the main [README on GitHub](https://github.com/Linuxfabrik/lfops) for detailed setup instructions
+
+
+## Links
+
+- [Ansible Galaxy](https://galaxy.ansible.com/ui/repo/published/linuxfabrik/lfops/)
+- [GitHub Repository](https://github.com/Linuxfabrik/lfops)
+- [Report an Issue](https://github.com/Linuxfabrik/lfops/issues/new/choose)
+- [Linuxfabrik Monitoring Plugins](https://linuxfabrik.github.io/monitoring-plugins/)
+- [Linuxfabrik Lib (Python libraries)](https://linuxfabrik.github.io/lib/lib.html)
+- [Linuxfabrik Website](https://www.linuxfabrik.ch)

tools/build-docs

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8; py-indent-offset: 4 -*-
+#
+# Author:  Linuxfabrik GmbH, Zurich, Switzerland
+# Contact: info (at) linuxfabrik (dot) ch
+#          https://www.linuxfabrik.ch/
+# License: The Unlicense, see LICENSE file.
+
+"""Generates the docs/ directory structure with symlinks and the mkdocs.yml navigation
+for the Linuxfabrik LFOps documentation site.
+
+Run this tool from the repository root directory.
+"""
+
+import os
+import sys
+
+__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
+__version__ = '2026040701'
+
+REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+DOCS_DIR = os.path.join(REPO_ROOT, 'docs')
+
+# Top-level markdown files to include in the documentation.
+# Format: (source filename, target filename in docs/, nav title or None for hidden)
+TOP_LEVEL_DOCS = [
+    ('CHANGELOG.md', 'CHANGELOG.md', None),
+    ('CODE_OF_CONDUCT.md', 'CODE_OF_CONDUCT.md', None),
+    ('COMPATIBILITY.md', 'compatibility.md', 'Compatibility'),
+    ('CONTRIBUTING.md', 'contributing.md', 'Contributing'),
+    ('SECURITY.md', 'security.md', 'Security'),
+    ('STIGs.md', 'stigs.md', 'STIGs'),
+]
+
+# Playbooks README
+PLAYBOOKS_README = ('playbooks/README.md', 'playbooks.md', 'Playbooks')
+
+
+def create_symlink(source, target):
+    """Create a relative symlink from target to source."""
+    target_dir = os.path.dirname(target)
+    rel_source = os.path.relpath(source, target_dir)
+    if os.path.islink(target):
+        os.unlink(target)
+    elif os.path.exists(target):
+        os.unlink(target)
+    os.symlink(rel_source, target)
+
+
+def scan_roles():
+    """Scan roles/ directory and return sorted list of role names that have a README.md."""
+    roles_path = os.path.join(REPO_ROOT, 'roles')
+    if not os.path.isdir(roles_path):
+        return []
+    roles = []
+    for entry in sorted(os.listdir(roles_path)):
+        if entry == 'example':
+            continue
+        readme = os.path.join(roles_path, entry, 'README.md')
+        if os.path.isfile(readme):
+            roles.append(entry)
+    return roles
+
+
+def generate_mkdocs_yml(roles):
+    """Generate the mkdocs.yml content."""
+    lines = []
+    lines.append("# This file is auto-generated by tools/build-docs. Do not edit manually.")
+    lines.append("")
+    lines.append("site_name: 'Linuxfabrik LFOps'")
+    lines.append("site_url: 'https://linuxfabrik.github.io/lfops/'")
+    lines.append("repo_url: 'https://github.com/Linuxfabrik/lfops'")
+    lines.append("repo_name: 'Linuxfabrik/lfops'")
+    lines.append("")
+    lines.append("theme:")
+    lines.append("  name: 'material'")
+    lines.append("  icon:")
+    lines.append("    logo: 'material/ansible'")
+    lines.append("  palette:")
+    lines.append("    - scheme: 'default'")
+    lines.append("      primary: 'blue grey'")
+    lines.append("      accent: 'orange'")
+    lines.append("      toggle:")
+    lines.append("        icon: 'material/brightness-7'")
+    lines.append("        name: 'Switch to dark mode'")
+    lines.append("    - scheme: 'slate'")
+    lines.append("      primary: 'blue grey'")
+    lines.append("      accent: 'orange'")
+    lines.append("      toggle:")
+    lines.append("        icon: 'material/brightness-4'")
+    lines.append("        name: 'Switch to light mode'")
+    lines.append("  features:")
+    lines.append("    - content.code.copy")
+    lines.append("    - navigation.expand")
+    lines.append("    - navigation.instant")
+    lines.append("    - navigation.sections")
+    lines.append("    - navigation.top")
+    lines.append("    - search.highlight")
+    lines.append("    - search.suggest")
+    lines.append("    - toc.follow")
+    lines.append("")
+    lines.append("markdown_extensions:")
+    lines.append("  - admonition")
+    lines.append("  - attr_list")
+    lines.append("  - def_list")
+    lines.append("  - tables")
+    lines.append("  - toc:")
+    lines.append("      permalink: true")
+    lines.append("")
+    lines.append("plugins:")
+    lines.append("  - search")
+    lines.append("")
+    lines.append("validation:")
+    lines.append("  links:")
+    lines.append("    not_found: 'info'")
+    lines.append("")
+    lines.append("not_in_nav: |")
+    lines.append("  CHANGELOG.md")
+    lines.append("  CODE_OF_CONDUCT.md")
+    lines.append("")
+
+    # Build nav
+    lines.append("nav:")
+    lines.append("  - 'Home': 'index.md'")
+    lines.append("  - 'Compatibility': 'compatibility.md'")
+    lines.append("  - 'Playbooks': 'playbooks.md'")
+    lines.append("  - 'Roles':")
+    for role in roles:
+        lines.append(f"      - '{role}': 'roles/{role}.md'")
+    lines.append("  - 'STIGs': 'stigs.md'")
+    lines.append("  - 'Contributing': 'contributing.md'")
+    lines.append("  - 'Security': 'security.md'")
+    lines.append("")
+
+    return '\n'.join(lines)
+
+
+def main():
+    os.makedirs(DOCS_DIR, exist_ok=True)
+
+    # Create symlinks for top-level docs
+    for source_name, target_name, _ in TOP_LEVEL_DOCS:
+        source = os.path.join(REPO_ROOT, source_name)
+        target = os.path.join(DOCS_DIR, target_name)
+        if os.path.isfile(source):
+            create_symlink(source, target)
+        else:
+            print(f'WARNING: {source_name} not found, skipping.')
+
+    # Create symlink for playbooks README
+    source_name, target_name, _ = PLAYBOOKS_README
+    source = os.path.join(REPO_ROOT, source_name)
+    target = os.path.join(DOCS_DIR, target_name)
+    if os.path.isfile(source):
+        create_symlink(source, target)
+    else:
+        print(f'WARNING: {source_name} not found, skipping.')
+
+    # Create symlinks for role READMEs
+    roles = scan_roles()
+    target_dir = os.path.join(DOCS_DIR, 'roles')
+    os.makedirs(target_dir, exist_ok=True)
+
+    # Remove stale symlinks
+    expected_files = {f'{role}.md' for role in roles}
+    for entry in os.listdir(target_dir):
+        entry_path = os.path.join(target_dir, entry)
+        if os.path.islink(entry_path) and entry not in expected_files:
+            os.unlink(entry_path)
+
+    for role in roles:
+        source = os.path.join(REPO_ROOT, 'roles', role, 'README.md')
+        target = os.path.join(target_dir, f'{role}.md')
+        create_symlink(source, target)
+
+    # Generate mkdocs.yml
+    mkdocs_content = generate_mkdocs_yml(roles)
+    mkdocs_path = os.path.join(REPO_ROOT, 'mkdocs.yml')
+    with open(mkdocs_path, 'w') as f:
+        f.write(mkdocs_content)
+
+    total_symlinks = len(TOP_LEVEL_DOCS) + 1 + len(roles)  # +1 for playbooks README
+    print(f'Created {total_symlinks} symlinks in docs/')
+    print(f'Generated mkdocs.yml with {len(roles)} role entries')
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())