# habibmrad/n8n-docs architecture

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

- Interactive diagram: https://gitdiagram.com/habibmrad/n8n-docs
- Repository: https://github.com/habibmrad/n8n-docs

## Overview

##### Project type and purpose
- This is a documentation site repository, built with MkDocs and the Material theme, serving n8n’s docs at docs.n8n.io.
- It contains markdown content (under docs/, _snippets/, _overrides/), styling (styles/), tooling scripts (_doctools/), config files (mkdocs.yml, nav.yml), CI workflows (.github/workflows), and hosting config (netlify.toml, CNAME).

##### Main components
a. Source code repository (GitHub)
- markdown content
- styles & overrides
- Python build scripts and requirements
- submodules (insiders)
- CI config files
b. Developer environment
- local clone + Python virtualenv
- pip install dependencies & insiders plugin
- mkdocs serve (live preview)
c. CI/CD pipeline (GitHub Actions)
- workflows: lint, build-test, deploy-preview, lexicon checks
- triggers on push, PR, schedule
- artifacts: validated docs, preview site
d. Site builder
- MkDocs (reads mkdocs.yml, nav.yml, docs/*, overrides/*, snippets/*, styles/*)
- Material theme plugin
- custom doctools scripts (_doctools) during build
e. Hosting platform
- Netlify (reads netlify.toml)
- DNS via CNAME to docs.n8n.io
f. End users
- browse static documentation
- assets: images, videos, CSS, JS

##### Relationships and data flow
- Developer → GitHub (push)
- GitHub Actions → MkDocs build & lint → preview deployment (Netlify Preview)
- On merge to main → CI triggers production build → Netlify publishes to docs.n8n.io
- End user requests docs.n8n.io → served from Netlify CDN → static assets delivered

##### Architectural patterns and design principles
- Static site generation (SSG) pattern: markdown → MkDocs → HTML/CSS/JS
- Git-driven content management with CI enforcement
- Component separation: content (docs/), design (styles/, _overrides/), tooling (_doctools/)
- Infrastructure-as-Code for CI/CD (.github/workflows) and hosting (netlify.toml)
- Submodule usage to include proprietary or insider features

##### Technologies, frameworks, and libraries
- Python 3.8+ and pip for build scripts
- MkDocs and Material for MkDocs theme
- GitHub Actions for CI/CD
- Netlify for hosting and preview builds
- _doctools scripts for custom link styling/page info
- Vale linting via .vale.ini for style checks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actors
    Developer["Developer Machine"]:::external
    EndUser["End User Browser"]:::external

    %% Source repository grouping
    subgraph "GitHub Repository" 
        direction TB
        RepoCode["GitHub Repo"]:::code

        docs["docs/"]:::code
        snippets["_snippets/"]:::code
        overrides["_overrides/"]:::code
        styles["styles/"]:::code
        vale[".vale.ini"]:::code

        subgraph "Custom Build Tooling"
            direction TB
            changeLink["_doctools/change_link_style.py"]:::code
            pageInfo["_doctools/pageinfo.py"]:::code
        end

        subgraph "MkDocs Config"
            direction TB
            mkdocsYml["mkdocs.yml"]:::code
            navYml["nav.yml"]:::code
            mkdocsTest["mkdocs-test.yml"]:::code
        end

        subgraph "Python Build Env"
            direction TB
            reqs["requirements.txt"]:::code
            runtime["runtime.txt"]:::code
            mainEntry["main.py"]:::code
        end

        insiders["_submodules/insiders/"]:::code

        subgraph "CI/CD Config"
            direction TB
            lint[".github/workflows/lint.yml"]:::process
            buildTest[".github/workflows/build-test.yml"]:::process
            lexi[".github/workflows/lexi.yml"]:::process
            lychee[".github/workflows/lychee.yml"]:::process
            lycheePr[".github/workflows/lychee-pr-check.yml"]:::process
            support[".github/workflows/support.yml"]:::process
        end

        netlifyToml["netlify.toml"]:::infra
        cname["CNAME"]:::infra

        bugTemplate[".github/ISSUE_TEMPLATE/bug_report.md"]:::code
        newDocs[".github/ISSUE_TEMPLATE/new-docs-request.md"]:::code
    end

    %% CI/CD grouping
    subgraph "GitHub Actions CI/CD" 
        direction TB
        CI["GitHub Actions"]:::process
    end

    %% Builder grouping
    subgraph "MkDocs Builder" 
        direction TB
        Builder["MkDocs + Material Theme + Doctools"]:::process
    end

    Static["Static Site Artifacts"]:::code

    subgraph "Netlify Hosting"
        direction TB
        Netlify["Netlify"]:::infra
    end

    %% Flow
    Developer -->|"git push"| RepoCode
    RepoCode -->|"trigger workflows"| CI
    CI -->|"invoke build & lint"| Builder
    Builder -->|"generate site"| Static
    Static -->|"deploy"| Netlify
    Netlify -->|"serve docs.n8n.io"| EndUser

    %% Click events
    click docs "https://github.com/habibmrad/n8n-docs/tree/main/docs/"
    click snippets "https://github.com/habibmrad/n8n-docs/tree/main/_snippets/"
    click overrides "https://github.com/habibmrad/n8n-docs/tree/main/_overrides/"
    click styles "https://github.com/habibmrad/n8n-docs/tree/main/styles/"
    click vale "https://github.com/habibmrad/n8n-docs/blob/main/.vale.ini"
    click changeLink "https://github.com/habibmrad/n8n-docs/blob/main/_doctools/change_link_style.py"
    click pageInfo "https://github.com/habibmrad/n8n-docs/blob/main/_doctools/pageinfo.py"
    click mkdocsYml "https://github.com/habibmrad/n8n-docs/blob/main/mkdocs.yml"
    click navYml "https://github.com/habibmrad/n8n-docs/blob/main/nav.yml"
    click mkdocsTest "https://github.com/habibmrad/n8n-docs/blob/main/mkdocs-test.yml"
    click reqs "https://github.com/habibmrad/n8n-docs/blob/main/requirements.txt"
    click runtime "https://github.com/habibmrad/n8n-docs/blob/main/runtime.txt"
    click mainEntry "https://github.com/habibmrad/n8n-docs/blob/main/main.py"
    click insiders "https://github.com/habibmrad/n8n-docs/tree/main/_submodules/insiders/"
    click lint "https://github.com/habibmrad/n8n-docs/blob/main/.github/workflows/lint.yml"
    click buildTest "https://github.com/habibmrad/n8n-docs/blob/main/.github/workflows/build-test.yml"
    click lexi "https://github.com/habibmrad/n8n-docs/blob/main/.github/workflows/lexi.yml"
    click lychee "https://github.com/habibmrad/n8n-docs/blob/main/.github/workflows/lychee.yml"
    click lycheePr "https://github.com/habibmrad/n8n-docs/blob/main/.github/workflows/lychee-pr-check.yml"
    click support "https://github.com/habibmrad/n8n-docs/blob/main/.github/workflows/support.yml"
    click netlifyToml "https://github.com/habibmrad/n8n-docs/blob/main/netlify.toml"
    click cname "https://github.com/habibmrad/n8n-docs/tree/main/CNAME"
    click bugTemplate "https://github.com/habibmrad/n8n-docs/blob/main/.github/ISSUE_TEMPLATE/bug_report.md"
    click newDocs "https://github.com/habibmrad/n8n-docs/blob/main/.github/ISSUE_TEMPLATE/new-docs-request.md"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#3B7A9E,color:#003049
    classDef process fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef infra fill:#FFE4B5,stroke:#CC8400,color:#CC8400
    classDef external fill:#E0E0E0,stroke:#888888,color:#333333
```
