Skip to main content

Golem Documentation

Michael Bernstein

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog ,

and this project adheres to Semantic Versioning .

Unreleased

Added

  • CLI Build & Serve Enhancements: Added -q/--quiet flag and elapsed execution timing to golem build, along with startup compilation status and live rebuild progress in golem serve.
  • Server-Side Syntax Highlighting: Pygments-powered syntax highlighting integrated into the build pipeline with Fired Clay styling.
  • Project Hygiene & CI Checks: Added CONTRIBUTING.adoc contributor guide and AST-based CI canary test (tests/test_syntax_invariants.py).
  • Test Coverage Configuration: Added pytest-cov and coverage[toml] to dev dependencies with configured targets in pyproject.toml.

Changed

  • Plugin Execution Gating: Refactored get_plugin_manager() to a two-pass discovery-registration architecture where config.plugins is the sole authority for activation and execution order.
  • Dependency Upgrades: Bumped asciidoctrine to >=0.2.0a4, asciidoctype to >=0.1.0a4, and added pygments>=2.18.
  • AsciiDoc Docstrings: Standardized docstrings across all internal modules to AsciiDoc format using asciidocstring conventions.
  • CSS Visual Hierarchy: Enhanced default theme typography, admonition pill labels, code listing language badges, table breakouts, and per-page layout classes.

Fixed

  • Python Exception Handling: Corrected five occurrences of deprecated Python 2 except A, B: syntax to Python 3 except (A, B):.
  • Plugin Hook Robustness: Isolated plugin exceptions across all build hooks and added conflict warnings when multiple plugins modify the same value.
  • Cross-Platform File Locking: Replaced POSIX-only fcntl cache locking with cross-platform filelock.
  • Configuration Normalization: Deduplicated TOML parsing across golem.toml and pyproject.toml into a centralized normalizer helper.
  • Navigation & TOC Performance: Cached discover_navigation() tree during build cycles and eliminated duplicated text in TOC anchor generation.
  • CLI Scaffolding & Metadata: Dynamically resolved --version from package metadata and author name from git config in golem init.
  • Repository Cleanliness: Removed internal review artifacts from tracking and added pattern ignores to .gitignore.
  • Dev Server Disconnects: Downgraded client socket disconnect exceptions to debug-level logging.

0.1.0a2 - 2026-08-24

Added

  • Fine-Grained Cache Invalidation (Issue #1):
  • AST/ASG node_types inventory recorded per page in .golem/cache.json.
  • Theme template fingerprinting and scoped cache invalidation for specific node template changes (e.g. listing.html only recompiles pages with code blocks).
  • New Pluggy lifecycle hook golem_mark_stale(changed_files, cache_metadata) enabling plugins to perform selective cache invalidation.
  • Automated API Documentation Generation (golem apidoc):
    • Built-in plugin golem.plugins.apidoc using Griffe and asciidocstring to introspect packages and generate clean AsciiDoc API reference documentation.

Changed

  • Upgraded Dependencies:
  • Upgraded asciidoctrine dependency requirement to >=0.2.0a3 (incorporating parser memoization, underscore emphasis fixes, and listing block bracket fixes).
  • Upgraded asciidoctest dependency requirement to >=0.2.0a3 (supporting AST section scoping and named test contexts).

Fixed

  • API Reference Formatting:
  • Description list multi-line formatting in apidoc output avoiding parser bloat.
  • Truncation of large inline attribute constants (such as HTML templates).
  • Heading level offset adjustment for docstrings opening with section headings.

0.1.0a1 - 2026-08-18

Added

  • Incremental DAG Build Engine: Dependency tracking with SHA-256 content hashing in .golem/cache.json, rebuilding only modified files and their inclusion dependents.
  • AsciiDoc Native Pipeline: Integration with asciidoctrine (Lark AST parser/ASG resolver) and asciidoctype (Chameleon ZPT templates) supporting 39 standard node types.
  • Hierarchical Navigation Auto-Discovery: Automatic sidebar tree generation with numeric prefix stripping (01-intro.adoc -> Intro), homepage pinning, and explicit golem.toml overrides.
  • Multi-Threaded Live Dev Server: Zero-dependency ThreadingHTTPServer with Server-Sent Events (SSE) live browser reload under /golem-reload and interactive compiler error overlays.
  • Pluggy Plugin Architecture: Lifecycle hooks for on_pre_parse, on_ast_created, on_asg_created, on_post_render, and golem_add_subcommands.
  • CLI Inspection Commands: golem plugins and golem themes commands to discover, inspect, and list active and installed extensions.
  • Doctest Integration: Executable Python code example verification in listing blocks using asciidoctest.
  • Fired Clay / Workbench Default Theme:
    • Handcrafted warm paper / workbench aesthetic with automatic prefers-color-scheme: dark mode.
    • Complete typography system built on Google Fonts Source family (Source Serif 4 for display/body, Source Sans 3 for UI chrome, Source Code Pro for monospaced code blocks).
    • Sub-perceptible SVG feTurbulence paper-grain texture data URIs.
    • Distinct earth-tone admonition palette (NOTE, TIP, IMPORTANT, WARNING, CAUTION).
  • Comprehensive Documentation Suite: Complete user manual, developer guide, and technical specification rewritten as focused, topic-grouped guides.

Fixed

  • TOC Scroll Anchors & Description Lists: Fixed table-of-contents slug anchors and description list node rendering.
  • Navigation Pruning: Pruned empty non-AsciiDoc directories and defaulted plugin lists cleanly to avoid empty navigation nodes.