HTML Comment Reference

HTML Comment Tracking

For files where YAML frontmatter would be visible in renders (README files, documentation), Strayfiles supports invisible HTML comment metadata.

Format

<!-- strayfiles: {"enabled": true, "id": "uuid-here"} -->

# Your Document

Content here...

The comment is invisible when rendered on GitHub, GitLab, or any Markdown viewer.

Placement

HTML comments must appear at the start of the file (whitespace allowed before):

Valid:

<!-- strayfiles: {"enabled": true} -->

# Content

Valid (with leading whitespace):

<!-- strayfiles: {"enabled": true} -->

# Content

Invalid (after content):

# Content

<!-- strayfiles: {"enabled": true} -->

Supported Fields

All frontmatter fields work in HTML comments:

Field	Type	Description
enabled	boolean	Opt file into tracking
id	string	Stable UUID (auto-generated)
workspaces	array	Virtual workspace assignments
sync	boolean	Set false for local-only
alias	string	Display name in UI

Examples

Minimal:

<!-- strayfiles: {"enabled": true} -->

With workspaces:

<!-- strayfiles: {"enabled": true, "workspaces": ["work", "docs"]} -->

With alias (for multiple README files):

<!-- strayfiles: {"enabled": true, "alias": "Backend README"} -->

Local-only sensitive docs:

<!-- strayfiles: {"enabled": true, "sync": false} -->

Full metadata:

<!-- strayfiles: {"enabled": true, "id": "550e8400-e29b-41d4-a716-446655440000", "workspaces": ["api", "docs"], "alias": "API Docs"} -->

When to Use

Scenario	Recommendation
Personal notes	YAML frontmatter
README files	HTML comment
GitHub-rendered docs	HTML comment
Files with existing frontmatter	YAML frontmatter
Static site content	YAML frontmatter

Priority

If a file has both YAML frontmatter and an HTML comment, frontmatter takes priority. The HTML comment is ignored.

Metadata Precedence

When multiple metadata sources exist, Strayfiles follows this priority order:

Priority	Source	Description
1 (highest)	YAML Frontmatter	In-file strayfiles: block
2	HTML Comment	<!-- strayfiles: {...} -->
3	Project TOML	./strayfiles.toml auto-assignment
4 (lowest)	User TOML	~/.strayfiles/strayfiles.toml

How it works:

1. ID extraction: Frontmatter ID is used if present, otherwise HTML comment ID
2. Workspace assignment: Explicit frontmatter workspaces override TOML auto-assignment
3. TOML precedence: Project TOML overrides User TOML for the same settings

Example:

A file with frontmatter workspaces: ["personal"] in a directory matching [workspaces.work].include will belong to “personal” only—frontmatter wins.

See Metadata Precedence for more details and examples.

JSON Format

The metadata uses JSON (not YAML) inside the comment:

• Keys must be quoted: "enabled" not enabled
• Use true/false for booleans
• Arrays use brackets: ["a", "b"]

Invalid (YAML syntax):

<!-- strayfiles: enabled: true -->

Valid (JSON syntax):

<!-- strayfiles: {"enabled": true} -->

Comparison: Frontmatter vs HTML Comment

Feature	YAML Frontmatter	HTML Comment
Visible in renders	Usually yes	No
Format	YAML	JSON
Rich metadata	Full support	Full support
Static site compatible	Yes	Yes
GitHub rendering	Shows frontmatter	Clean render