package
Interpolate strings with HTML comment markers
npm install comment-markGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Read and update sections of Markdown using HTML comment placeholders.
Keep generated content, like contributor lists and benchmark results, alongside handwritten documentation. The placeholders stay in the file after each update, so the same Markdown serves as both the template and the output.
pnpm add comment-markIn README.md, wrap the content you want to update with matching :start and :end comments:
## Last updated
<!-- lastUpdated:start --><!-- lastUpdated:end -->Read the file, pass values keyed by marker name, and save the result:
import fs from 'node:fs/promises'
import { commentMark } from 'comment-mark'
const markdown = await fs.readFile('README.md', 'utf8')
const updated = commentMark(markdown, {
lastUpdated: '2026-09-07'
})
await fs.writeFile('README.md', updated)## Last updated
<!-- lastUpdated:start -->2026-09-07<!-- lastUpdated:end -->Run the script again with a new value to replace the section. The surrounding document and marker comments stay intact. For a live timestamp, use new Date().toISOString() as the value.
Use the CLI to read or update a file without writing a script:
npx comment-mark <file> [--<marker>=<value>...]file is the path to a Markdown or HTML file. The examples below use npx; package scripts can call comment-mark directly.
Pass each value as --<marker>=<value>. For the placeholder in the quick start:
npx comment-mark README.md --lastUpdated="2026-09-07"Set multiple markers in one invocation:
npx comment-mark README.md --contributors="Jane Doe" --lastUpdated="2026-09-07" --benchmarks="result"For a file with a stale contributors section, a lastUpdated section already containing 2026-09-07, and no benchmarks marker, the command writes the contributor update and reports on stderr:
Updated: contributors
Unchanged: lastUpdated
Missing: benchmarks
Saved README.md. Updated 1 key; 1 unchanged; 1 missing.| Status | Meaning |
|---|---|
Updated | The marker exists and applying the value changes the document |
Unchanged | Applying the value leaves the section unchanged |
Missing | No matching marker exists |
When updates are saved alongside missing markers, the command exits 1. If every requested marker is missing, it exits 1 without writing. If all requested markers exist and their values already match, it exits 0 without rewriting the file.
Omit marker flags to print the detected values as JSON on stdout:
npx comment-mark README.mdFor the quick-start result:
{
"lastUpdated": "2026-09-07"
}Pipe the result to jq to select a value:
npx comment-mark README.md | jq -r '.lastUpdated'Read mode preserves section whitespace and prints {} when no markers exist. It exits non-zero if the file cannot be read or a start marker has no matching end comment.
--last-updated does not match a lastUpdated marker.--key=value, not --key value. Quote values containing spaces or newlines.--key= to clear a section. Multiline values get a newline before and after the supplied content.--help, -h, and --version work without a file. Markers named help or version remain settable with --help=<value> or --version=<value>.commentMark(input, data)Replace marked sections with values from data. This function transforms content in memory; it does not read or write files.
import { commentMark } from 'comment-mark'
const updated = commentMark('Version: <!-- version:start -->1.0.0<!-- version:end -->', {
version: '2.0.0'
})
console.log(updated)
// Version: <!-- version:start -->2.0.0<!-- version:end -->input (string | Buffer): Markdown or HTML contentdata (Record<string, string | null | undefined>): Values keyed by marker nameReturns the updated content as a string. Buffer input is decoded as UTF-8.
null and undefined values. An empty string clears the section.\n in an additional newline on each side.getCommentMarks(input)Read marked sections into an object keyed by marker name:
import { getCommentMarks } from 'comment-mark'
const sections = getCommentMarks('Version: <!-- version:start -->2.0.0<!-- version:end -->')
console.log(sections.version)
// 2.0.0input (string | Buffer): Markdown or HTML contentRecord<string, string> with no inherited properties. Missing sections have no property.<!-- version:start --> reads as the key version.Add a section to README.md:
## Contributors
<!-- contributors:start --><!-- contributors:end -->Fill it with the output of git shortlog:
npx comment-mark README.md --contributors="$(git shortlog -se HEAD -- .)"For a repository with two contributors, the result looks like:
## Contributors
<!-- contributors:start -->
17 John Doe <john.doe@example.com>
5 Jane Smith <jane.smith@example.com>
<!-- contributors:end -->Shell command substitution removes trailing newlines. For multiline values, comment-mark adds a newline at each end so the content sits between the marker lines.
projects.json on each Git commitHTML comments are hidden in rendered Markdown but remain visible in the source. They mark where generated content belongs without adding visible template syntax to the document.
The start and end comments delimit the content to replace. Both stay in the output, so later updates can find the same section without a separate template file.
Estimated unpacked size across 5 packages.
215.8 kB
Includes dependencies.