How vapor/docs works
Project type and purpose
• This is the “Vapor Documentation” repository: a static-site documentation generator and publisher for the Vapor Swift web framework.
• It uses MkDocs (Python) with a custom theme (Liquid/Leaf) plus Swift scripts to build search indices and redirects. CI/CD is handled via GitHub Actions, and containerization is via Docker Compose.
File structure
• Top level:
• Dockerfile + docker-compose.yaml – container definition for local dev and CI builds
• mkdocs.yml – MkDocs config (nav structure, languages, plugins)
• docs/ – Markdown content in multiple languages under subfolders (basics, advanced, deploy, etc.)
• theme/ – Jinja2/Liquid templates, CSS, JS for styling and syntax highlighting
• fixSearchIndex.swift, setUpRedirects.swift – Swift scripts run post-build to patch search index and generate redirects
• .github/workflows – CI jobs: check (lint, build-serve tests) and deploy (build & publish to docs.vapor.codes)
• requirements.txt – Python dependencies for MkDocs plugins and multilingual support
README for additional insights
• Local development: docker compose up spins up a container with Python3 and MkDocs serving on port 8000.
• Translators add <filename>.<lang>.md and update mkdocs.yml under languages and nav_translations.
• CI pipeline builds all enabled languages and deploys to docs.vapor.codes.
a. Main components
• Developer (local machine)
• Version Control & CI/CD (GitHub + Actions)
• Build Container (Docker Compose image running Python3 + MkDocs + Swift)
• Source Content (docs/ + theme/)
• Build Scripts (fixSearchIndex.swift, setUpRedirects.swift)
• Static Site Output (HTML/CSS/JS)
• Hosting / CDN (docs.vapor.codes)
• End User’s Browser
b. Relationships & interactions
1. Developer pushes commits or pull requests (including translation updates) to GitHub.
2. GitHub Actions “check” workflow:
– Spins up Docker container, installs Python deps, runs mkdocs build or mkdocs serve --check
– Validates links, front-matter, nav consistency, translation completeness.
3. On merge to main, CI’s “deploy” workflow:
– Builds static site inside container (mkdocs build).
– Executes fixSearchIndex.swift to regenerate the search index JSON.
– Executes setUpRedirects.swift to produce redirect templates.
– Publishes the site/ folder to the hosting target (possibly GitHub Pages or a CDN behind docs.vapor.codes).
4. End user navigates to docs.vapor.codes; CDN serves the pre-built static HTML/CSS/JS.
c. Architectural patterns and design principles
– Static site generation: source (Markdown + templates) → build pipeline → immutable artifacts.
– Containerized reproducible builds (Docker ensures consistency across dev machines and CI).
– CI/CD as code (GitHub Actions) integrates build, test, deploy.
– i18n with file-based content organization and mkdocs.yml language toggles.
– Post-build scripting for non-MkDocs tasks (search indexing, redirect rules) using Swift.
d. Key technologies, frameworks, or libraries
– Docker & Docker Compose
– Python3 + MkDocs + MkDocs-material or custom plugins
– Liquid/Leaf templates for theming
– Swift scripts (fixSearchIndex.swift, setUpRedirects.swift)
– GitHub Actions workflows
– CDN or GitHub Pages for hosting
Key reminders
• Be very detailed: capture both the build-time (CI, container, scripts) and run-time (static hosting, browser) aspects.
• Don’t over-complicate: separate into logical components (Source, Build, Publish, Consume) and show interactions.
• Essential architectural elements are visible: i18n content, containerization, CI stages, and hosting.