embed-src 3.3.0

Syntax

Place opening and closing markers in your file using whatever comment style is appropriate:

Markdown / HTML:

<!-- embed-src src="path/to/config.yml" -->
<!-- /embed-src -->

Rust / JS / Go / C:

// embed-src src="path/to/utils.py"
// /embed-src

Python / Shell / YAML:

# embed-src src="path/to/setup.sh"
# /embed-src

CSS:

/* embed-src src="path/to/theme.css" */
/* /embed-src */

SQL / Lua:

-- embed-src src="path/to/schema.sql"
-- /embed-src

When the tool runs, the content between the markers is replaced with the referenced file's contents.

Raw vs Fenced Insertion

By default, content is inserted raw (no wrapping). This works for any file type.

To wrap content in markdown code fences, use the fence attribute:

Attribute	Behavior
(none)	Raw insertion
`fence`	Code fence with auto-detected language
`fence="auto"`	Code fence with auto-detected language
`fence="python"`	Code fence with explicit language tag

Example with fencing:

<!-- embed-src src="path/to/config.yml" fence="auto" -->
```yaml
server:
  host: localhost
  port: 8080
```
<!-- /embed-src -->

Paths are relative to the host file's directory.
The code fence language is inferred from the file extension when using fence or fence="auto".
Re-running is idempotent -- existing content between markers is replaced.

Features

Any File Type: Embed into markdown, YAML, Python, Rust, or any file with comments.
Raw or Fenced: Insert raw content by default, or wrap in code fences with fence.
Custom Commit Options: Personalize commit messages, author details, and push behavior.
Dry-Run Mode: Test embedding without creating commits.
Seamless Integration: Drop into any GitHub Actions workflow.

Installation

Script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/urmzd/embed-src/main/install.sh | sh

Installs the latest release to $HOME/.local/bin and adds it to your shell's PATH.

Options (environment variables):

Variable	Description	Default
`EMBED_SRC_VERSION`	Version to install (e.g. `v3.1.1`)	latest
`EMBED_SRC_INSTALL_DIR`	Installation directory	`$HOME/.local/bin`

Example — pin a version:

EMBED_SRC_VERSION=v3.1.1 curl -fsSL https://raw.githubusercontent.com/urmzd/embed-src/main/install.sh | sh

Manual

Download a pre-built binary for your platform from the releases page and place it somewhere on your PATH.

Windows — the script installer is not supported; use the manual download above.

Local Usage

The embed-src binary can also be used directly:

# Process files in place
embed-src README.md docs/*.md

# Check if files are up-to-date (CI mode)
embed-src --verify README.md

# Preview changes without writing
embed-src --dry-run README.md

Inputs

Name	Description	Required	Default
`files`	Space-separated list of files to process.	No	`README.md`
`commit-message`	Commit message for the embedded changes.	No	`chore: embed source files`
`commit-name`	Git committer name.	No	`github-actions[bot]`
`commit-email`	Git committer email.	No	`github-actions[bot]@users.noreply.github.com`
`commit-push`	Whether to push after committing.	No	`true`
`commit-dry`	Skip the commit (dry-run mode).	No	`false`
`github-token`	GitHub token for downloading the binary.	No	`${{ github.token }}`

Usage

Basic

name: "Example"

on: [push]

jobs:
  embed:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: "Checkout repo"
        uses: actions/checkout@v4
      - name: "Embed code into files"
        uses: urmzd/embed-src@v1.5.0
        with:
          files: "README.md"

Multiple Files

- uses: urmzd/embed-src@v2
  with:
    files: "README.md docs/API.md docs/GUIDE.md"

Dry Run (No Commit)

Useful for CI validation -- embed the files and check for drift without committing:

- uses: urmzd/embed-src@v2
  with:
    commit-dry: "true"
    commit-push: "false"

Troubleshooting

Action fails with "nothing to commit" This means no changes were needed. Ensure your files contain valid embed-src markers with src="..." and corresponding /embed-src closing markers.

Permission denied on push The action needs contents: write permission. Add this to your job:

permissions:
  contents: write

Files not being embedded Verify the file paths in files are relative to the repository root and that the referenced source files exist.

Agent Skill

This project ships an Agent Skill for use with Claude Code, Cursor, and other compatible agents.

Install:

npx skills add urmzd/embed-src

Once installed, use /embed-src to embed source files into documents using comment markers.

Internal Use

We use Embed Src in our own CI/CD pipelines, ensuring our documentation is always synchronized with the latest code.