webtyp.com/markdown

markdown

Markdown document reader, frontmatter parser and section updater. Zero dependencies.

The package does no I/O of its own: the caller injects the read and write functions, so the same Doc works over the filesystem, an embed.FS, or an in-memory buffer.

import "webtyp.com/markdown"

Doc

New(rootDir, destination, writeFile) returns a Doc. Set its input with one of:

Input	Use for
InputPath(path, readFile)	a file on disk
InputByte(content)	markdown already in memory
InputEmbed(path, readFile)	a path inside an embed.FS (or any reader)

Extract fenced code blocks

Extract(outputFile) concatenates every fenced block whose language matches the output file's extension and writes the result to destination/outputFile. Blocks of any other language are ignored.

Extension	Fence language
.go	```go
.js	```javascript
.css	```css

code := ""
capture := func(name string, data []byte) error { code = string(data); return nil }

err := markdown.New("", ".", capture).
    InputByte(template).
    Extract("main.go")

The output file is left untouched when the extracted code is identical, so regenerating does not bump its mtime and does not retrigger file watchers.

Frontmatter

ParseFrontmatter(content) returns the leading --- block as a map[string]string.

meta, err := markdown.New(".", "", nil).
    InputPath("docs/PLAN.md", os.ReadFile).
    Frontmatter()

meta["tag"] // "v0.2.0"

Rules: the block must start at byte 0 with --- and close at the next ---. Each line is a key: value pair split on the first colon (so a URL value keeps its own colons); lines without a colon are skipped; surrounding quotes are stripped; CRLF is tolerated.

Which keys are required is not this package's business — that belongs to whoever defines the document's schema. An empty block is valid and parses to an empty map. The only errors are structural:

Error	When
ErrFrontmatterMissing	the document does not open with ---
ErrFrontmatterUnclosed	the opening --- has no closing ---

Update a delimited section

UpdateSection(id, content, afterLine...) creates or replaces the block between <!-- START_SECTION:id --> and <!-- END_SECTION:id -->, writing the document back.

err := markdown.New(".", ".", writeFile).
    InputPath("README.md", os.ReadFile).
    UpdateSection("BADGES_SECTION", badges, "1") // place it after line 1

• Duplicate sections with the same id are collapsed into one.
• afterLine is a 1-based line number used when the section does not exist yet, or to relocate it; without it, a new section is appended at the end.
• The document is left untouched when the section is already up to date.

License

MIT