# next-theme/theme-next-docs architecture

> Architecture diagram of the GitHub repository next-theme/theme-next-docs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/next-theme/theme-next-docs
- Repository: https://github.com/next-theme/theme-next-docs

## Overview

##### Project Type and Purpose
- This is a **static documentation website** for the NexT Hexo theme.
- It’s built with **Hexo** (Node.js) to transform content (Markdown, Nunjucks templates, Stylus) into a static site.
- It uses **CI/CD** (GitHub Actions + Netlify) to automate builds and deploy to a CDN.

##### Main Components
A. Developer Workspace
– Source code repository (GitHub)
– Local dev tools: Node.js, npm, Hexo CLI
– Configuration files: `_config.yml`, `_config.next.yml`, `netlify.toml`
B. Content & Templates
– `source/` (Markdown posts, docs, assets, Nunjucks templates under `_data`)
– `lib/` and `scripts/` (custom build scripts: syntax highlighting, data updates)
C. Build Engine
– Hexo core: reads configs + content + templates → generates static files
– Stylus compiler (CSS), Nunjucks renderer, Highlight.js integration
D. CI/CD
– GitHub Actions (`.github/workflows/codeql.yml`): code scanning, test hooks
– Netlify (via `netlify.toml` or `deploy.sh`): on merge, pulls repo → runs `npm install`, `npx hexo generate` → deploys `public/` to global CDN
E. End Users & Third-Party Services
– Site visitors (browsers) request static assets from CDN
– Optional integrations: analytics, search, comments, chat (configured in docs/third-party-services)

##### Relationships and Data Flows
1. Developer pushes commits → GitHub repo
2. GitHub Actions runs code scans/tests
3. On successful main-branch update, Netlify/`deploy.sh` builds site:
- npm install → Hexo generate → output in `public/`
4. Netlify pushes `public/` to CDN
5. Browsers fetch static HTML/CSS/JS → render documentation
6. Integrated third-party services (analytics, comments) load as external scripts at runtime

##### Key Architectural Patterns & Principles
- **Static Site Generation**: clear separation of content (Markdown/templating) and generated output
- **Modular templating**: data files under `source/_data/` + Nunjucks partials (for easy theme customization)
- **CI/CD pipeline**: automated build & deploy on every merge, ensuring docs always up-to-date
- **Extensibility**: plugin folders (`source/tag-plugins`, `source/docs/third-party-services`) showcase how to add new features without core changes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workspace
    subgraph "Developer Workspace" 
        direction TB
        DevTools["Node.js & Hexo CLI"]:::devCI
        PkgJson["package.json"]:::devCI
        ConfigYml["_config.yml"]:::devCI
        ConfigNext["_config.next.yml"]:::devCI
        DevTools -->|"defines scripts/config"| PkgJson
        DevTools -->|"uses configs"| ConfigYml
        DevTools -->|"uses configs"| ConfigNext
    end

    %% CI/CD Configuration
    subgraph "CI/CD Configuration"
        direction TB
        CodeQL[".github/workflows/codeql.yml"]:::devCI
        NetlifyToml["netlify.toml"]:::devCI
        DeploySh["deploy.sh"]:::devCI
    end

    %% Version Control & CI
    GitHubRepo[(GitHub Repo)]:::devCI
    GitHubActions["GitHub Actions"]:::devCI
    NetlifyBuild["Netlify Build"]:::devCI

    DevTools -->|git push| GitHubRepo
    GitHubRepo -->|triggers| GitHubActions
    GitHubActions -->|on main merge| NetlifyBuild

    %% Build Engine
    subgraph "Build Engine" 
        direction TB
        HexoEngine["Hexo Engine\n(npx hexo generate)"]:::build
        Stylus["Stylus Compiler"]:::build
        Nunjucks["Nunjucks Renderer"]:::build
        HighlightJS["Highlight.js Integration"]:::build
    end

    NetlifyBuild -->|runs npm install\nand hexo generate| HexoEngine
    HexoEngine -->|compiles CSS| Stylus
    HexoEngine -->|renders templates| Nunjucks
    HexoEngine -->|applies syntax highlighting| HighlightJS

    %% Content & Templates
    subgraph "Content & Templates"
        direction TB
        SourceDir["source/"]:::build
        DataDir["source/_data/"]:::build
        PostsDir["source/_posts/"]:::build
        LibDir["lib/"]:::build
        ScriptsDir["scripts/"]:::build
    end

    SourceDir -->|provides content| HexoEngine
    DataDir -->|provides templates/styles| HexoEngine
    PostsDir -->|provides posts| HexoEngine
    LibDir -->|provides custom scripts| HexoEngine
    ScriptsDir -->|provides custom scripts| HexoEngine

    %% Configuration usage in build
    ConfigYml -.->|reads| HexoEngine
    ConfigNext -.->|reads| HexoEngine
    NetlifyToml -.->|configures| NetlifyBuild
    DeploySh -.->|runs| NetlifyBuild
    CodeQL -.->|scans| GitHubRepo

    %% Deployment and Serving
    PublicDir["public/"]:::build
    CDN((CDN)):::external
    Browser{{Browser}}:::external
    ThirdParty["Third-Party Services"]:::external

    HexoEngine -->|outputs static files| PublicDir
    PublicDir -->|deploys static site| CDN
    CDN -->|HTTP GET static assets| Browser
    Browser -->|loads scripts| ThirdParty

    %% External integrations
    subgraph "Third-Party Integrations"
        direction TB
        ThirdPartyDocs["source/docs/third-party-services/"]:::external
        RobotsTxt["source/robots.txt"]:::external
    end

    ThirdPartyDocs -->|runtime load| Browser
    RobotsTxt -->|serves to crawlers| Browser

    %% Click Events
    click PkgJson "https://github.com/next-theme/theme-next-docs/blob/master/package.json"
    click ConfigYml "https://github.com/next-theme/theme-next-docs/blob/master/_config.yml"
    click ConfigNext "https://github.com/next-theme/theme-next-docs/blob/master/_config.next.yml"
    click CodeQL "https://github.com/next-theme/theme-next-docs/blob/master/.github/workflows/codeql.yml"
    click NetlifyToml "https://github.com/next-theme/theme-next-docs/blob/master/netlify.toml"
    click DeploySh "https://github.com/next-theme/theme-next-docs/blob/master/deploy.sh"
    click SourceDir "https://github.com/next-theme/theme-next-docs/tree/master/source/"
    click DataDir "https://github.com/next-theme/theme-next-docs/tree/master/source/_data/"
    click PostsDir "https://github.com/next-theme/theme-next-docs/tree/master/source/_posts/"
    click LibDir "https://github.com/next-theme/theme-next-docs/tree/master/lib/"
    click ScriptsDir "https://github.com/next-theme/theme-next-docs/tree/master/scripts/"
    click HighlightJS "https://github.com/next-theme/theme-next-docs/blob/master/lib/highlight.js"
    click ThirdPartyDocs "https://github.com/next-theme/theme-next-docs/tree/master/source/docs/third-party-services/"
    click RobotsTxt "https://github.com/next-theme/theme-next-docs/blob/master/source/robots.txt"

    %% Styles
    classDef devCI fill:#AED6F1,stroke:#1F618D,color:#1B2631
    classDef build fill:#A9DFBF,stroke:#196F3D,color:#1B2631
    classDef external fill:#F9E79F,stroke:#B9770E,color:#1B2631
```
