How dragonman225/notablog works
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).