Acknowledgements
Braised Docs stands on the shoulders of several excellent projects. This page documents the tools and projects we depend on, the design decisions we borrowed from them, and the license context for each.
Inspirations
Hugo
Hugo's architecture directly shaped several of Braised's internal patterns:
- Template inheritance via
{{block}}/{{define}}— we use Go'shtml/templatein the same way Hugo does, with a base layout that defines named blocks, and user overrides via{{define}}in partial files. partialCachedpattern — pre-rendering the nav tree once per build and reusing the HTML string across all pages is the same technique Hugo uses to avoid re-executing expensive partials on every page.- Embedded defaults — the built-in layout and assets are embedded in the binary via
embed.FS, so the tool works without any external files. Hugo does the same with its built-in themes. nav.yamlas an explicit site map — Hugo'sconfig.yamlmenu definitions inspired the decision to make navigation a separate, explicit file rather than inferring it from folder structure.
Sphinx
Sphinx set the standard for documentation-grade build tools:
- Never fail fast — Braised collects all build errors across all pages and reports them together at the end. A broken page is skipped, not an abort. This mirrors Sphinx's behavior exactly and is the right default for documentation workflows where partial output is still useful.
- Directive syntax — the
:::blockfence syntax is a simplified version of Sphinx's reStructuredText directive concept, adapted for Markdown.
Goldmark
Goldmark (Yuin Sato) is the Markdown parser at Braised's core, and also the parser Hugo migrated to. The extension API (goldmark.Extender, parser.BlockParser, renderer.NodeRenderer) is what makes Braised's block system possible. The :::block fences are implemented as a Goldmark AST extension.
Dependencies
Runtime dependencies
These ship with the braised binary or are required at build time.
| Project | Use | License |
|---|---|---|
| goldmark | Markdown parser | MIT |
| goldmark-meta | Frontmatter (YAML in Markdown) | MIT |
| goldmark-fences | Referenced when building the custom :::block parser; not a runtime dependency (see note below) |
MIT |
| fsnotify | File watching (braised serve) |
BSD-3-Clause |
| cobra | CLI framework | Apache-2.0 |
| yaml.v3 | YAML parsing (braised.yaml, nav.yaml) | MIT / Apache-2.0 |
| buntdb | In-memory KV store (ref index) | MIT |
| mcp-go | MCP server support | MIT |
| Alpine.js | Reactive UI for blocks (tabs, pillstrip, filter) | MIT |
Note on goldmark-fences: We studied goldmark-fences while designing the :::block fence parser and found a stack-leak bug in its NoChildren handling that caused incorrect nesting. Rather than patching an upstream library, we wrote internal/block/parser.go as a standalone Goldmark BlockParser implementation. goldmark-fences shaped our understanding of the extension API and deserves credit even though it is not a runtime dependency. The upstream repository has seen no commits, issues, or pull requests in over four years, so contributing a fix upstream did not seem like a productive path.
Optional / user-installed
| Project | Use | License |
|---|---|---|
| Tailwind CSS v4 | CSS pipeline (standalone CLI) | MIT |
Test-only dependencies
| Project | Use | License |
|---|---|---|
| testify | Assertions in unit tests | MIT |
| chromedp | Browser-based integration tests | MIT |
| goleak | Goroutine leak detection in tests | MIT |