README
¶
md2html
Convert existing Markdown documentation to HTML. One static binary, no configuration, no runtime.
go install github.com/AdamF-G/md2html/cmd/md2html@latest
md2html ./docs -o ./site
What it does
Walks your docs, follows links between documents across directories, and
writes a browsable HTML tree. Tables get scroll containers, headings get
anchors, .md links become .html links, and mermaid fences render as
diagrams. Markdown also gets a few extras beyond CommonMark/GFM: fenced
containers (::: callout … :::) for callouts, warnings, cards and
collapsible asides/examples; [proven]-style status chips; §4.2
cross-references that autolink to numbered headings; a [[toc]] marker for
a per-page contents list; title/subtitle/date front matter; a
caption="…" attribute on code fences; and a fig fence for hand-laid-out
diagrams — boxes, arrows and panels described in YAML, for layouts a
mermaid graph cannot express.
The one thing a generated page fetches at view time is MermaidJS, and only
a page that actually contains a diagram: it loads a pinned build from a CDN.
Pages without diagrams reference nothing external, and --fragment output
never loads it at all, because Artifacts render mermaid themselves. A build
that must not reach a CDN can name its own copy — see Options.MermaidURL
below.
Usage
md2html [flags] <entry> [entry...]
Entries may be files or directories.
md2html ./docs -o ./site # whole tree
md2html ./docs --depth 0 -o ./site # top-level seeds, still follows links
md2html ./docs/index.md ./guides -o ./site # mixed entries
md2html ./docs # in place, beside each source
md2html ./docs -o ./site --fragment # Artifact-shaped output
md2html README.md # one file, HTML beside it
# The maintained set, plus one scratch directory for this run only,
# with a vendored subtree another tool owns left strictly alone.
md2html -o ./site ./docs ./scratch/notes --exclude vendor
Two kinds of reach
Links between documents are followed across directories, unbounded by
default. --depth and --link-depth bound two different things: --depth
limits how deep into a directory md2html looks for unlinked files to seed
from; --link-depth limits how many hops from a seed link-following may
travel. Both read the same way: -1 is unlimited (the default for each),
and a non-negative number is the bound itself, so --link-depth 0 follows
no links at all. --depth 0 seeds only the Markdown sitting directly in
the directory — and, with --link-depth left at its default, still follows
every link out of it, however far that leads.
Where output goes
With -o, everything lands inside it. Documents under the entry points
mirror their relative paths; documents pulled in from elsewhere on disk go
under _external/, mirroring their absolute path. Nothing is ever written
outside -o.
Without -o, HTML is written beside each source, and links that would
escape the entry tree are refused rather than followed.
Assets are linked, never copied
An image stays where it is. Its link is rewritten to point back at the original, climbing out of the output directory as far as needed:
docs/api/auth.md -> site/api/auth.html
./img/flow.png -> ../../docs/api/img/flow.png
So the output tree is self-contained for documents but not for assets.
Move site/ on its own and images break; move it alongside the sources and
they do not. That is the deliberate trade for never duplicating your files.
It will not overwrite your work
Every generated file starts with:
<!-- generated by https://github.com/AdamF-G/md2html v0.2.0 - edits will be overwritten -->
Re-runs replace files carrying that marker silently. A file without it is never touched — md2html warns, skips it, and exits non-zero. There is no override flag. The marker carries the full repository URL, so output from unrelated tools that share the name is never claimed.
Flags
| Flag | Effect |
|---|---|
-o DIR |
output directory; default writes beside each source |
--depth N |
directory levels to seed from a directory entry; -1 (default) unlimited |
--link-depth N |
hops from a seed that link-following may travel; -1 (default) unlimited, 0 follows none |
--fragment |
emit Artifact-shaped fragments instead of full pages |
--css FILE |
replace the embedded stylesheet |
--no-table-scroll |
do not wrap tables |
--no-anchors |
do not add heading anchors |
--no-external-links |
do not mark external links |
--no-md-links |
do not rewrite .md links |
--no-assets |
do not rewrite asset links |
--exclude DIR |
never enter, seed, follow into, or write to DIR (relative to the base — the common ancestor of the entry points — or absolute); repeatable, or comma-separated |
--version |
print the version and exit; the same version the provenance marker carries |
Writing docs for it
Callouts, diagrams, heading attributes, footnotes and definition lists all work, and one of them fails silently if you get the syntax wrong. See docs/authoring.md.
Library use
import "github.com/AdamF-G/md2html"
out, err := md2html.Convert(src, md2html.Options{SourcePath: "doc.md"})
Options.Warn, when set, receives one message per non-fatal problem found
while converting a document. Three things report so far: a front matter
block that isn't flat key: value, a container naming a kind that doesn't
exist, and a fig fence whose body doesn't parse or doesn't validate. All
three arrive whatever Transforms holds — a builtin that reports is rebuilt
against this sink before it runs, so appending to Builtins() costs you no
diagnostics. Convert never writes to stderr itself; the callback runs
synchronously on the calling goroutine.
Options.MermaidURL names the ES module a page with a diagram imports at
view time, for a docs build that must not reach a CDN. Empty keeps the
pinned build.
Add a transform by writing a func(*html.Node) error:
ts := append(md2html.Builtins(), md2html.Transform{
Name: "myRule",
Fn: func(root *html.Node) error { /* walk and mutate */ return nil },
})
out, err := md2html.Convert(src, md2html.Options{Transforms: ts})
Transforms run over a real HTML tree, so they reach hand-written raw HTML in your Markdown as well as generated markup.
Development
just install builds the binary and installs it to ~/.local/bin, then
prints the version it just installed:
just install # to ~/.local/bin
just bindir=/somewhere/else install # anywhere else
It refuses to install into a directory that does not already exist, rather
than creating one: go install will happily create a missing GOBIN and
every level above it, which on a fresh machine puts the binary somewhere
nothing on PATH will ever read and still reports success.
just test (or go test ./...) needs no browser. A separate suite drives
real headless Chrome to exercise the click-to-expand JavaScript runtimes
end to end:
just e2e # or: cd e2e && go test ./...
It requires Chrome or Chromium installed locally, and lives in e2e/ as its
own Go module. That boundary is the only opt-in — there is no build tag —
and it is what keeps chromedp out of the library: a test-only import would
sit in this module's own go.mod as a direct requirement and be compiled by
anyone who ran its tests. Nothing in a build or test of the library
compiles it now. (It does still appear in go.mod as an indirect entry:
go.abhg.dev/goldmark/mermaid requires it for a server-side renderer
md2html never imports. That one is inherited, and the split cannot remove
it.)
GitHub Actions runs both suites on every push and pull request, along with
gofmt, go vet and go mod tidy -diff. CHANGELOG.md
records what has changed.
License
MIT
Documentation
¶
Overview ¶
Package md2html converts Markdown documents to HTML with tree-level transforms that reach hand-written raw HTML as well as generated markup.
Index ¶
Constants ¶
const MarkerPrefix = "<!-- generated by https://github.com/AdamF-G/md2html"
MarkerPrefix is the stable portion of the provenance marker. Detection matches this prefix only, so files written by older versions are still recognized. It carries the full repository URL rather than the bare tool name, so output from an unrelated tool also called md2html is never mistaken for ours.
const Version = "v0.2.0"
Version is stamped into the provenance marker.
Variables ¶
This section is empty.
Functions ¶
func IsMarkdownPath ¶
IsMarkdownPath reports whether p names a Markdown document.
Types ¶
type CrawlOptions ¶
type CrawlOptions struct {
// Entries are the starting points: files, directories, or both.
Entries []string
// OutDir is the output root. Empty means in-place.
OutDir string
// Depth bounds how many directory levels a directory entry seeds.
// 0 seeds only files directly inside it; -1 is unlimited. It never
// affects link traversal; LinkDepth, below, bounds that instead.
Depth int
// NoMdLinks leaves document links unrewritten.
NoMdLinks bool
// NoAssets leaves asset links unrewritten.
NoAssets bool
// Exclude lists directory prefixes that must never be entered. Each
// value is either absolute or relative to the resolved base. A path at
// or beneath one is never seeded, never followed as a link target, and
// never written to; a link pointing at one keeps its href exactly as
// written, the same handling a link escaping base gets in in-place mode.
//
// This exists for subtrees some other tool already owns — a slide-deck
// renderer, a vendored dependency's own generated docs, a frozen
// archive. Without it the only way to keep the crawler out of one is to
// move it out of the source tree, which is rarely possible.
Exclude []string
// LinkDepth bounds how far link-following may travel from a seed,
// counted in hops: a document a seed links to is one hop, one it links
// to in turn is two.
//
// It reads exactly as Depth does: a non-negative value is the bound
// itself, and -1 is unlimited. 0 therefore follows no links at all,
// which is what makes a zero-valued CrawlOptions coherent rather than
// merely conservative — Depth's zero already seeds a directory's own
// files and none of its subdirectories, so both fields describe the
// smallest possible run, and the CLI asks for unlimited on both.
LinkDepth int
}
CrawlOptions configures a discovery pass.
type CrawlResult ¶
type CrawlResult struct {
// Docs is the emit set: every document reachable from the entry points.
Docs []Doc
// Base is the deepest directory containing every entry point.
Base string
// External lists the resolved absolute paths of documents pulled in
// from outside Base.
External []string
// Warnings are the non-fatal problems found during the crawl.
Warnings []Warning
}
CrawlResult is the outcome of a discovery pass.
func Crawl ¶
func Crawl(opt CrawlOptions) (*CrawlResult, error)
Crawl discovers every document reachable from the entry points.
type Doc ¶
type Doc struct {
// Src is the resolved absolute source path.
Src string
// Out is the absolute destination path for the generated HTML.
Out string
// LinkMap maps an href exactly as written in this document to its
// replacement. Populated by buildLinkMaps.
LinkMap map[string]string
}
Doc is one document in the emit set.
type Link ¶
type Link struct {
// Href is the value exactly as written in the source.
Href string
// Kind classifies the link target.
Kind LinkKind
// Abs is the resolved absolute path, for LinkDoc and LinkAsset only.
// Any #fragment has been stripped.
Abs string
// Node is the element carrying the link, so a transform can rewrite it.
Node *html.Node
// Attr is the attribute on Node carrying the link ("href" or "src").
Attr string
}
Link is one href or src found in a document.
type Options ¶
type Options struct {
// Fragment emits Artifact shape (marker, title, style, body) instead of
// a full HTML document.
Fragment bool
// Title overrides the derived title. Empty means derive from the first
// <h1>, falling back to SourcePath's base name.
Title string
// SourcePath is the absolute path of the source document. Used for the
// title fallback and diagnostics.
SourcePath string
// CSS replaces the embedded default stylesheet. Empty uses the default.
CSS string
// MermaidURL is the ES module a page containing a mermaid diagram
// imports at view time. Empty uses the pinned CDN build.
//
// It is the only thing a generated page ever fetches, so this is the
// knob for a docs build that must not reach a CDN: point it at a copy
// you serve yourself. Nothing else changes — a page with no diagram
// still imports nothing, and Fragment output never imports at all,
// because Artifacts render mermaid themselves.
MermaidURL string
// Transforms to run. Nil means the default list.
//
// A list supplied here is used as given, except that any builtin in it
// that reports diagnostics is rebuilt against Warn — so appending to
// Builtins() keeps every warning a default conversion would have
// raised, without the caller naming the sink twice. The caller's own
// slice is never written to.
//
// Transforms and LinkMap are two alternative routes to link rewriting,
// not complementary ones: either place LinkRewrite in Transforms
// yourself, or set LinkMap and let Convert do it. Doing both rewrites
// every href twice — see LinkMap.
Transforms []Transform
// LinkMap maps an href exactly as written in the source to its
// replacement. Populated by the crawler; nil for standalone conversion.
//
// Setting this makes Convert append LinkRewrite(LinkMap) to the
// transform list itself, so callers must not also put LinkRewrite in
// Transforms. Two passes over one map corrupt output whenever a
// replacement is itself a key: a document linking both ./a.md (mapped
// to a.html) and an existing ./a.html asset (mapped to the original
// file) would have the first rewrite turned into the second.
LinkMap map[string]string
// Warn, when non-nil, receives one message per non-fatal problem found
// while converting this document. Three things report so far: a front
// matter block that is not flat key: value, a container naming a kind
// that does not exist, and a fig fence whose body does not parse or
// does not validate.
//
// Convert never writes to stderr itself: it is a library, and the CLI
// emits every document's output in parallel, so a transform printing
// directly would interleave with other documents' lines. The callback
// is invoked synchronously on the calling goroutine, so a caller may
// append to an unsynchronized per-document slice.
//
// Every source reaches it by the same route whatever Transforms holds:
// Convert raises the front matter warning itself, the fig fence warning
// comes from the renderer, and a transform that reports is rebuilt
// against this sink before it runs (see Transforms).
Warn func(string)
}
Options controls a single document conversion.
type Transform ¶
type Transform struct {
// Name identifies the transform, e.g. for logging or diagnostics.
Name string
// Fn is the function applied to the parsed HTML tree.
Fn func(*html.Node) error
}
Transform mutates a parsed HTML tree in place. Fn receives the synthetic root node whose children are the document's top-level elements.
func Builtins ¶
func Builtins() []Transform
Builtins returns the transforms enabled by default.
It takes no arguments and reports nothing: it is the documented public door for callers assembling their own transform list (see README), and changing its signature would break them. A list built from it still reports — Convert rebuilds the entries in warnAware against Options.Warn before running them — so the nil sink here costs a caller nothing.
func Chips ¶
func Chips() Transform
Chips turns a fixed set of bracketed tokens into small styled badges, everywhere inline Markdown is rendered — body text and headings alike, since a status marker on a heading is the case the convention exists for.
A heading's marker is kept out of its slug by HeadingAnchors, which is why this transform must run before it.
func Containers ¶
Containers normalizes fenced containers. It accepts the brace-free "::: kind" form as an alias for "::: {.kind}", maps the shipped kinds onto their stylesheet classes, warns when a brace-free name is not one of them, and drops the fence library's internal data-fence attribute.
warn may be nil.
func ExternalLinks ¶
func ExternalLinks() Transform
ExternalLinks marks off-site links so they open in a new tab without leaking the referring window.
func HeadingAnchors ¶
func HeadingAnchors() Transform
HeadingAnchors gives every heading a stable id and a linkable anchor. An id already present — from a {#custom-id} attribute — is left alone.
Status chips are excluded from the slug: a marker is metadata about the section, not part of its name, and relabeling one later must not rot an anchor other documents already link to.
func LinkRewrite ¶
LinkRewrite replaces hrefs and srcs using a map keyed by the link exactly as written in the source document. Links absent from the map are left untouched, which is how remote URLs, fragments, and deliberately unrewritten links survive.
func SectionLinks ¶
func SectionLinks() Transform
SectionLinks autolinks bare "§N.M" references to the heading in the same document numbered N.M.
It is a transform rather than a goldmark extension because it needs the finished heading set, ids included, to resolve against — which only exists after HeadingAnchors has run.
Left alone: a § inside a code span, code block or existing link (handled by rewriteText, via splitMatches only ever touching prose text nodes); a § whose number matches no heading here; and a possessive reference scoping the section to another document, as in "the design doc's §7". That last rule is narrow — it catches the possessive phrasing and nothing else — so a cross-document reference written any other way still needs a code span to opt out.
func TOC ¶
func TOC() Transform
TOC replaces a marker paragraph with a flat list of the current document's own headings.
Flat, not nested by heading level: a document that jumps h2 to h4 would otherwise produce either invalid list nesting or a silently wrong tree. Level travels as a class on the list item, so the stylesheet can indent without the markup having to be a hierarchy.
This is a table of contents for one page and nothing more. Cross-document navigation, a sidebar and a site index stay out of scope — see docs/specs/2026-09-11-extended-content-model.md, item 6.
func TableScroll ¶
func TableScroll() Transform
TableScroll wraps every table in a horizontally scrollable container, so wide tables never force the page body to scroll sideways. It reaches hand-written tables in raw HTML as well as generated ones.
type Warning ¶
type Warning struct {
// Src is the document the warning was raised while processing, or, for
// a warning with no document to point at (an --exclude value that
// matches nothing on disk), the offending value itself.
Src string
// Message describes the problem.
Message string
}
Warning is a non-fatal problem found during a run.
type WriteResult ¶
type WriteResult int
WriteResult reports what SafeWrite did.
const ( // WriteCreated means no file existed at the destination. WriteCreated WriteResult = iota // WriteOverwritten means an earlier generated file was replaced. WriteOverwritten // WriteRefused means a file we did not write was left untouched. WriteRefused )
func SafeWrite ¶
func SafeWrite(path string, data []byte) (WriteResult, error)
SafeWrite writes data to path, refusing to destroy any file this tool did not generate. Parent directories are created as needed.
A refusal is a WriteRefused result, not an error: the caller continues with other files and reports the refusal in the run summary.
Source Files
Directories