# dragonman225/notablog architecture

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

- Interactive diagram: https://gitdiagram.com/dragonman225/notablog
- Repository: https://github.com/dragonman225/notablog

## Overview

##### Project type and purpose
- Notablog is a Node.js command-line static site generator (CLI tool) that reads a Notion database (table), transforms its pages into HTML using themes and templates, and outputs a minimalistic blog.

##### File structure
- bin/cli.js: entry point for the CLI (“notablog generate” and “notablog preview”).
- package.json, rollup.config.js, tsconfig.json: build and packaging config for distributing the CLI.
- src/commands/: two sub-commands: generate.ts (site generation) and preview.ts (local preview server).
- src/cache.ts: cache layer for storing parsed Notion pages.
- src/ntable.ts, src/parseTable.ts, src/table.ts: Notion-table retrieval and AST parsing.
- src/renderer.ts, src/renderIndex.ts, src/renderPost.ts, src/templateProvider.ts: rendering pipeline—load templates, inject data, produce HTML.
- src/utils/: helper modules (misc, Notion API wrapper).
- assets/: static images for README.
- test/: unit tests for cache, ntable parser, renderer, utilities.
- tools/upgrade-deps.js: helper script.

##### README for additional insights
- Describes two workflows: generate and preview.
- Describes starter project structure (config.json, public/, cache/, themes/).
- Explains cache-driven re-render logic: skip unchanged pages.
- Themes use EJS templates and static assets.
- Preview spins up a static server and optionally launches a browser.

##### Main components and their interactions
a. CLI Layer
- Input: user invokes “notablog generate <path>” or “notablog preview <path>.”
- Dispatches to GenerateCommand or PreviewCommand.
b. Config Loader
- Reads config.json from notablog-starter folder (URL, theme, previewBrowser, autoSlug, locales).
c. Notion API Adapter (src/utils/notion.ts)
- Fetches raw table data from Notion.
d. Cache Module (src/cache.ts)
- Compares timestamps, stores/reads NAST representations in cache folder.
e. Parser (src/parseTable.ts, ntable.ts, table.ts)
- Converts Notion data into intermediate “page metadata” and AST.
f. Renderer
- TemplateProvider: resolves theme layouts (index, post, tag).
- renderIndex, renderPost: injects PageMetadata & contentHTML into EJS templates.
- Outputs HTML & static assets into public/ directory.
g. Preview Server (in preview.ts)
- Serves public/ folder over HTTP, optionally opens browser.

##### Architectural patterns and design principles
- Layered pipeline: CLI → Config → Fetch → Cache → Parse → Render → FS.
- Separation of concerns: distinct modules for caching, parsing, rendering, commands.
- Plugin-style theme engine: themes directory with manifests and EJS layouts.
- Idempotent generation: cache avoids re-render of unchanged pages.
- Test coverage: individual units tested (parser, cache, renderer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entry\nbin/cli.js"]:::internal
        Gen["GenerateCommand\nsrc/commands/generate.ts"]:::internal
        PrevCmd["PreviewCommand\nsrc/commands/preview.ts"]:::internal
    end

    %% Config Loader
    Config["Config Loader\nsrc/config.ts"]:::config

    %% Notion Adapter & External API
    Adapter["Notion Adapter\nsrc/utils/notion.ts"]:::internal
    NotionAPI["Notion API"]:::external

    %% Cache
    Cache["Cache Module\nsrc/cache.ts"]:::storage

    %% Parser
    subgraph Parser
        NTable["Notion Table Retrieval\nsrc/ntable.ts"]:::internal
        TableMeta["Metadata Handling\nsrc/table.ts"]:::internal
        ParseTable["AST Conversion\nsrc/parseTable.ts"]:::internal
    end

    %% Renderer
    subgraph Renderer
        Core["Renderer Core\nsrc/renderer.ts"]:::internal
        TemplateProv["TemplateProvider\nsrc/templateProvider.ts"]:::internal
        IndexR["Index Page\nsrc/renderIndex.ts"]:::internal
        PostR["Post Page\nsrc/renderPost.ts"]:::internal
    end

    %% File System & Preview
    FS["Public Output\n(public/)"]:::storage
    PreviewSrv["Preview Server"]:::internal
    Browser["Browser"]:::external

    %% Utilities & Types
    Util["Utility Helpers\nsrc/utils/misc.ts"]:::utility
    Types["Type Definitions\nsrc/types.ts"]:::utility

    %% Build & Tools
    BuildConf["Build & Packaging\npackage.json\nrollup.config.js\ntsconfig.json"]:::config
    Tools["Dependency Upgrade\ntools/upgrade-deps.js"]:::utility

    %% Test Suite
    subgraph Tests
        CacheTest["Cache Tests\ntest/cache/cache.spec.ts"]:::test
        ParserTest["Parser Tests\ntest/ntable.spec.ts"]:::test
        RendererTest["Renderer Tests\ntest/renderer/renderer.spec.ts"]:::test
        UtilTest["Utility Tests\ntest/util.spec.ts"]:::test
    end

    %% Data Flow
    CLI --> Gen
    CLI --> PrevCmd

    Gen --> Config
    Config --> Adapter
    Adapter --> NotionAPI
    Adapter --> Cache

    Cache --> NTable
    NTable --> TableMeta
    TableMeta --> ParseTable
    Cache --> ParseTable

    ParseTable --> Core
    Core --> TemplateProv
    TemplateProv --> IndexR
    TemplateProv --> PostR
    Core --> IndexR
    Core --> PostR

    IndexR --> FS
    PostR --> FS

    PrevCmd --> FS
    FS --> PreviewSrv
    PreviewSrv --> Browser

    BuildConf --> CLI
    Tools --> CLI

    Util --> Adapter
    Types --> Core

    %% Tests Coverage
    CacheTest --> Cache
    ParserTest --> NTable
    RendererTest --> Core
    UtilTest --> Util

    %% Click Events
    click CLI "https://github.com/dragonman225/notablog/blob/master/bin/cli.js"
    click Gen "https://github.com/dragonman225/notablog/blob/master/src/commands/generate.ts"
    click PrevCmd "https://github.com/dragonman225/notablog/blob/master/src/commands/preview.ts"
    click Config "https://github.com/dragonman225/notablog/blob/master/src/config.ts"
    click Adapter "https://github.com/dragonman225/notablog/blob/master/src/utils/notion.ts"
    click Cache "https://github.com/dragonman225/notablog/blob/master/src/cache.ts"
    click NTable "https://github.com/dragonman225/notablog/blob/master/src/ntable.ts"
    click TableMeta "https://github.com/dragonman225/notablog/blob/master/src/table.ts"
    click ParseTable "https://github.com/dragonman225/notablog/blob/master/src/parseTable.ts"
    click Core "https://github.com/dragonman225/notablog/blob/master/src/renderer.ts"
    click TemplateProv "https://github.com/dragonman225/notablog/blob/master/src/templateProvider.ts"
    click IndexR "https://github.com/dragonman225/notablog/blob/master/src/renderIndex.ts"
    click PostR "https://github.com/dragonman225/notablog/blob/master/src/renderPost.ts"
    click Util "https://github.com/dragonman225/notablog/blob/master/src/utils/misc.ts"
    click Types "https://github.com/dragonman225/notablog/blob/master/src/types.ts"
    click CacheTest "https://github.com/dragonman225/notablog/blob/master/test/cache/cache.spec.ts"
    click ParserTest "https://github.com/dragonman225/notablog/blob/master/test/ntable.spec.ts"
    click RendererTest "https://github.com/dragonman225/notablog/blob/master/test/renderer/renderer.spec.ts"
    click UtilTest "https://github.com/dragonman225/notablog/blob/master/test/util.spec.ts"
    click BuildConf "https://github.com/dragonman225/notablog/blob/master/package.json"
    click Tools "https://github.com/dragonman225/notablog/blob/master/tools/upgrade-deps.js"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366d6,stroke-width:1px
    classDef external fill:#FFE4B5,stroke:#d18b00,stroke-width:1px
    classDef storage fill:#DFFFE0,stroke:#027A11,stroke-width:1px,shape:cylinder
    classDef config fill:#FFF5BA,stroke:#B58200,stroke-width:1px
    classDef utility fill:#E8E8E8,stroke:#666666,stroke-width:1px
    classDef test fill:#FFDDE6,stroke:#D60050,stroke-width:1px,stroke-dasharray: 5 5
```
