MEGADOC Site Design & Architecture

Welcome to the heart of MEGADOC! This guide unlocks the secrets of our documentation platform—how it's built, how it looks, and how you can contribute to making it world-class.

---

Quick Navigation

• Platform Overview
• Design Principles
• Navigation Structure
• Visual Style Guide
• MkDocs Configuration
• Deployment Pipeline
• Best Practices
• Resources Next Steps

---

Platform Overview

MEGADOC is powered by MkDocs and the Material for MkDocs theme, extended with plugins for navigation, search, and monorepo support. All content lives in the docs/ folder, with submodules under submodules/—each with their own docs/ and mkdocs.yml.

• Build Output: The site/ folder is generated and served via Nginx, built with HashiCorp Packer (epic.pkr.hcl).
• Hosting: Containers run on the ARC platform (Nomad + Consul + HAProxy), bi-homed for high availability.
• CI/CD: GitHub Actions automate linting, submodule sync, and image builds for Terraform Enterprise deployment.

---

Design Principles

---

Navigation Structure

MEGADOC uses a hierarchical, task-oriented structure:

• Progressive Disclosure: Start simple, go deep.
• Cross-Referencing: Inline links and related docs at the bottom.
• Mobile-First: Collapsible sections, touch-friendly navigation.

---

Visual Style Guide

Typography:

• Roboto for body text
• Roboto Mono for code
• Headers: Bold, clear, and spaced for readability

Callouts:

• Use !!! info, !!! tip, !!! danger for important notes
• Tables for quick reference
• Mermaid diagrams for architecture visuals

---

MkDocs Configuration

Key settings in mkdocs.yml:

• Theme: Material for MkDocs, with custom palette and icons
• Plugins: exclude, git-revision-date-localized, tags, mike, search, include-markdown, monorepo (verify against the current top-level mkdocs.yml)
• Markdown extensions: admonition, attr_list, md_in_html, footnotes, pymdownx.superfences (with Mermaid custom fence), pymdownx.tabbed, pymdownx.details, pymdownx.blocks.*, pymdownx.emoji, pymdownx.highlight, and others — see mkdocs.yml for the authoritative list
• Navigation: Logical, hierarchical, and easy to follow

---

Deployment Pipeline

• Linting: Superlinter for Markdown and code
• Submodule Sync: Automated with GitHub Actions
• Build & Deploy: Image built for Terraform Enterprise, deployed to ARC
• Validation: Automated tests and link checks before deploy

---

Best Practices

---

Resources Next Steps

• Contributing Overview
• Writing Standards
• GitHub Workflow
• Publishing Process
• Submodules Guide
• Support & FAQ
• Advanced Markdown
• Best Practices

---

You now have the blueprint for MEGADOC's design system. Use these principles to create documentation that's clear, accessible, and a joy to use — for every team member, every time.