Embed Code

Embed Code is a Go command-line tool that keeps documentation snippets in sync with source files. It scans Markdown and HTML documents for <embed-code> instructions, resolves the requested source content, and manages the following code fence.

This project replaces the earlier embed-code utility for Ruby/Jekyll.

Start Here

The complete usage guide lives in the showcase. It covers configuration, embedding instructions, check mode, embed mode, expected failures, and runnable examples.

What It Does

• Embeds whole files, named fragments, source ranges, or matching source lines.
• Supports multiple named source roots for one documentation tree.
• Filters comments when examples should omit implementation notes.
• Processes Markdown and HTML documents.
• Runs in check mode for CI and embed mode to update documentation.

Run

Download the asset for your platform from GitHub Releases.

On Linux, for example:

./embed-code-linux -mode=check -config-path=showcase/embedding/embed-code.yml

It may be necessary to give the executable permission with chmod +x on Unix-like systems:

chmod +x embed-code-linux

Since binary file for macOS is not signed, it may be necessary to change its attributes to allow execution:

xattr -d com.apple.quarantine embed-code-macos

Or run it with Go:

go run ./main.go -mode=check -config-path=showcase/embedding/embed-code.yml

Use -mode=embed when documentation should be rewritten with current source content. See the configuration guide for all command-line flags and YAML options.

Build

Use Go 1.26.4.

go build -trimpath -o embed-code main.go

This creates embed-code on Unix-like systems or embed-code.exe on Windows. The -trimpath flag prevents local absolute paths from appearing in stack traces.

Development

Run the normal test suite:

go test ./...

Run the executable showcase:

go test -tags showcase ./showcase