june-docs

Documentation Platform Architecture

The June documentation platform (docs.june.4ofl.dev) is engineered as a decoupled static documentation site powered by VitePress 1.6, GitHub Actions, and an automated synchronization pipeline.

---

Decoupled Architecture

To protect proprietary operational workflows, private administrator tooling, and internal infrastructure secrets, the documentation product is decoupled into two repositories:

flowchart LR
    subgraph Private ["Private Monorepo (4ofl/june)"]
        Src["Bot Source Code (src/)"]
        OpsDoc["Internal Runbooks (ops/)"]
        PublicDocs["Public Docs Directory (docs/)"]
        GenScript["scripts/generate-docs.js"]
    end

    subgraph CI ["GitHub Actions CI/CD"]
        SyncWF["sync-docs.yml (Automated Sync)"]
        DeployWF["deploy.yml (GitHub Pages Build)"]
    end

    subgraph Public ["Public Docs Repo (4ofl/june-docs)"]
        DocsSite["VitePress Source & Theme"]
        GHMerged["Main Branch"]
    end

    subgraph CDN ["Production Edge"]
        Pages["GitHub Pages CDN\n(docs.june.4ofl.dev)"]
    end

    Src --> GenScript
    GenScript --> PublicDocs
    PublicDocs --> SyncWF
    SyncWF -->|Push to 4ofl/june-docs| GHMerged
    GHMerged --> DeployWF
    DeployWF --> Pages

1. 4ofl/june (Private Engine)

• Contains bot application code, native SQLite database logic, and internal operational runbooks (ops/).
• Owns the documentation contract and generates command reference specifications directly from Discord slash command builders.
• The sync-docs.yml workflow synchronizes only the sanitized docs/ tree to the public repository upon pushes to main.

2. 4ofl/june-docs (Public Documentation Platform)

• Standalone documentation product hosted as an open-source reference.
• Excludes bot tokens, internal compose setups, management guild IDs, and administrator commands.
• Compiles via VitePress and deploys to the custom domain https://docs.june.4ofl.dev/.

---

Static Site Generation & Theming

1. Engine: VitePress 1.6

June’s documentation runs on VitePress, Vue 3, and Vite. VitePress provides:

• Instant page transitions with client-side routing.
• Server-Side Rendering (SSR) during build time producing lightweight static HTML.
• Built-in local full-text search with zero external tracking scripts.
• Automated XML sitemap generation for search engine indexing.

2. Obsidian Design System

The visual presentation mirrors June’s Discord embed aesthetic and dashboard styling:

• Obsidian Dark Palette: #000000 base, #050507 surface layers, #111116 borders.
• Accent Highlighting: Emerald #10b981 accents and subtle emerald badge glows.
• Typography: Space Grotesk for headings, Inter for body copy, and JetBrains Mono for code blocks.
• Seamless Theme Switching: Smooth transitions between obsidian dark mode and high-contrast light mode.

---

Dynamic Vector Diagramming (Mermaid)

VitePress renders standard code blocks by default. June integrates an SSR-safe, client-side dynamic Mermaid diagramming engine in docs/.vitepress/theme/Layout.vue:

flowchart TD
    MD["Markdown with ```mermaid Fence"] --> HTML["Pre-rendered HTML Code Block"]
    HTML --> Mount["Vue Layout onMounted() Hook"]
    Mount --> Import["Dynamic Import: await import('mermaid')"]
    Import --> Init["Initialize with Obsidian Theme Tokens"]
    Init --> Render["mermaid.run(): Render Vector SVG in DOM"]

• SSR-Safe: Dynamic importing (await import('mermaid')) prevents server-side rendering crashes during static site compilation.
• Theme Reactivity: A Vue watcher observes isDark changes and re-renders SVG diagrams instantly to adapt stroke colors and node contrast.

---

SEO, Canonical Links & Metadata

Every page on docs.june.4ofl.dev automatically generates comprehensive search engine metadata:

• Canonical URLs: Dynamically generated canonical links pointing to https://docs.june.4ofl.dev/<page>.
• OpenGraph & Twitter Cards: Title, description, and preview metadata formatted per page.
• Sitemap: Clean XML sitemap emitted at /sitemap.xml on every build.
• Last Updated Timestamps: Git commit timestamps enabled via fetch-depth: 0 in GitHub Actions.