# ipfs/ipfs-docs architecture

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

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

## Overview

##### Project type and purpose
- This repository is the **IPFS documentation site**, a static-site application built with **VuePress**.
- Its sole purpose is to transform Markdown content and assets into a published docs website (https://docs.ipfs.tech), with an automated CI/CD pipeline and some code-generation tooling for API docs.

##### File structure
- Top-level sources:
- `docs/` – all Markdown content plus VuePress config under `docs/.vuepress/`.
- `images/` – static assets used in headers and case studies.
- `tools/http-api-docs/` – a Go-based code-generation utility to produce HTTP API reference from annotated endpoints.
- Configuration & scripts:
- `package.json` / `package-lock.json` – Node.js dependencies, dev scripts (`npm start`, `npm run build`).
- `.github/workflows/` and `.github/actions/` – GitHub Actions workflows and custom actions for tasks like “update with latest versions,” “latest-kubo-tag,” CI linting, building, deploying.
- `docs/.vuepress/config.js`, head.js, nav/ – VuePress site configuration, theming, plugin hooks.
- Linting and style:
- `.markdownlint.jsonc` / `.vale.ini` – enforce markdown/style rules.
- Dependabot and other automation configs under `.github/`.

##### README for additional insights
- Confirms use of **VuePress** as the static-site generator.
- Describes local dev (`npm start -> localhost:8080`) and troubleshooting, plus guidelines on CI/CD deploying to **Fleek** and tests run by CircleCI / GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Authoring Layer
    subgraph "Content Authoring Layer"
        direction TB
        docs_md["Markdown Files\n(docs/**/*.md)"]:::content
        images_assets["Images\n(images/)"]:::content
    end
    click docs_md "https://github.com/ipfs/ipfs-docs/tree/main/docs/"
    click images_assets "https://github.com/ipfs/ipfs-docs/tree/main/images/"

    %% VuePress Static Site Generator
    subgraph "VuePress Static Site Generator" 
        direction TB
        vp_config["config.js"]:::build
        vp_head["head.js"]:::build
        vp_nav["nav/en.js"]:::build
        vp_plugin["vuepress-plugin-speedcurve"]:::build
        vp_theme["theme/"]:::build
    end
    click vp_config "https://github.com/ipfs/ipfs-docs/blob/main/docs/.vuepress/config.js"
    click vp_head "https://github.com/ipfs/ipfs-docs/blob/main/docs/.vuepress/head.js"
    click vp_nav "https://github.com/ipfs/ipfs-docs/blob/main/docs/.vuepress/nav/en.js"
    click vp_plugin "https://github.com/ipfs/ipfs-docs/tree/main/docs/.vuepress/plugins/vuepress-plugin-speedcurve/"
    click vp_theme "https://github.com/ipfs/ipfs-docs/tree/main/docs/.vuepress/theme/"

    %% Code-Generation Tool
    subgraph "Code-Generation Tool (HTTP API docs)" 
        direction TB
        cg_endpoints["endpoints.go"]:::build
        cg_makefile["Makefile"]:::build
        cg_main["main.go"]:::build
    end
    click cg_endpoints "https://github.com/ipfs/ipfs-docs/blob/main/tools/http-api-docs/endpoints.go"
    click cg_makefile "https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs/Makefile"
    click cg_main "https://github.com/ipfs/ipfs-docs/blob/main/tools/http-api-docs/http-api-docs/main.go"

    %% Local Development Server
    subgraph "Local Development Server"
        direction TB
        pkg_json["package.json"]:::build
        pkg_lock["package-lock.json"]:::build
        dev_server["npm start → Dev Server"]:::build
    end
    click pkg_json "https://github.com/ipfs/ipfs-docs/blob/main/package.json"
    click pkg_lock "https://github.com/ipfs/ipfs-docs/blob/main/package-lock.json"

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        subgraph "Lint Stage"
            direction TB
            lint_md[".markdownlint.jsonc"]:::ci
            lint_vale[".vale.ini"]:::ci
            lint_action["markdownlint & Vale"]:::ci
        end
        subgraph "Generate Stage"
            direction TB
            run_codegen["Run Code-Generation Tool"]:::ci
        end
        subgraph "Build Stage"
            direction TB
            vp_build["VuePress Build"]:::ci
        end
        subgraph "Test Stage"
            direction TB
            test_codegen["Unit Tests (Go)"]:::ci
            test_snapshot["Snapshot Tests"]:::ci
        end
        subgraph "Deploy Stage"
            direction TB
            deploy_fleek["Deploy to Fleek"]:::ci
        end
        workflows[".github/workflows/"]:::ci
        actions_latest["latest-kubo-tag Action"]:::ci
        actions_update["update-with-latest-versions Action"]:::ci
        dependabot_cfg[".github/dependabot.yml"]:::ci
    end
    click workflows "https://github.com/ipfs/ipfs-docs/tree/main/.github/workflows/"
    click actions_latest "https://github.com/ipfs/ipfs-docs/tree/main/.github/actions/latest-kubo-tag/"
    click actions_update "https://github.com/ipfs/ipfs-docs/tree/main/.github/actions/update-with-latest-versions/"
    click dependabot_cfg "https://github.com/ipfs/ipfs-docs/blob/main/.github/dependabot.yml"

    %% Deployment Target
    fleek["Fleek Hosting\n(static via IPFS/CDN)"]:::external

    %% External Services
    gh["GitHub (SCM, Issues, PRs)"]:::external
    npmreg["npm Registry"]:::external

    %% Relationships
    docs_md -->|feeds into| vp_config
    images_assets -->|assets for| vp_theme
    cg_main -->|generates API docs| vp_plugin
    cg_endpoints --> cg_main
    cg_makefile --> cg_main

    vp_config --> vp_build
    vp_head --> vp_build
    vp_nav --> vp_build
    vp_plugin --> vp_build
    vp_theme --> vp_build

    pkg_json --> dev_server
    pkg_lock --> dev_server
    dev_server --> vp_build

    gh --> workflows
    gh --> lint_action
    gh --> run_codegen
    gh --> vp_build
    gh --> test_codegen
    gh --> deploy_fleek

    lint_md --> lint_action
    lint_vale --> lint_action
    workflows --> lint_action
    lint_action --> run_codegen
    run_codegen --> vp_build
    vp_build --> test_snapshot
    test_codegen --> test_snapshot
    test_snapshot --> deploy_fleek
    deploy_fleek --> fleek

    gh --> dependabot_cfg
    gh --> actions_latest
    gh --> actions_update
    workflows --> actions_latest
    workflows --> actions_update

    npmreg --> pkg_json

    %% Styles
    classDef content fill:#e0f7e9,stroke:#27a745,stroke-width:2px
    classDef build fill:#e0f0ff,stroke:#2d6cdf,stroke-width:2px
    classDef ci fill:#fff4e5,stroke:#f5a623,stroke-width:2px
    classDef external fill:#f4e5ff,stroke:#9b59b6,stroke-width:2px
```
