HTML Comment Basics

Invisible Metadata

For files where you don’t want visible frontmatter—like README files that render on GitHub—Strayfiles supports HTML comment metadata. The tracking data is completely invisible when rendered.

Basic Structure

Add a strayfiles comment at the start of any Markdown file:

<!-- strayfiles: {"enabled": true, "id": "550e8400-e29b-41d4-a716-446655440000"} -->

# My README

Your content here...

When viewed on GitHub, GitLab, or any Markdown viewer, only the heading and content appear—the comment is hidden.

Available Fields

Field	Type	Description
enabled	boolean	Opt this file into strayfiles indexing
id	string	Stable UUID for the file (auto-generated if omitted)
workspaces	array	Virtual workspaces this note belongs to
sync	boolean	Set to false to keep this file local-only (Pro)
alias	string	Display name shown instead of the filename

How It Works

"enabled": true

Tells strayfiles this file should be indexed. If your project uses explicit_only = true in the config, only files with this flag will be indexed.

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

"id" (optional)

A stable identifier for the file. Strayfiles auto-generates this on first index, but you can set it manually if needed. Useful for:

• Maintaining references when files move
• Syncing across devices
• API integrations

<!-- strayfiles: {"enabled": true, "id": "550e8400-e29b-41d4-a716-446655440000"} -->

"workspaces"

Assign notes to virtual workspaces without moving files:

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

"alias" (optional)

A display name shown in the browser instead of the filename. Useful when you have multiple files with the same name (like README.md in different projects):

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

When an alias is set, Strayfiles displays Backend API README (README.md) with the original filename dimmed.

"sync": false (Pro only)

Keep sensitive files local-only. Files with "sync": false are indexed and searchable but never uploaded to Stray Cloud, even with Stray Cloud enabled.

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

Use this for files containing:

• API keys or secrets
• Environment variables
• Database credentials
• Private configuration
• Anything sensitive

Even with end-to-end encryption, we recommend keeping secrets local. This gives you the best of both worlds: your sensitive files are searchable alongside everything else, but they never leave your device.

JSON Format

HTML comments use JSON (not YAML) for the metadata:

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

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

Placement

The comment must be at the start of the file (whitespace before is allowed):

Valid:

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

# Content

Invalid (after content):

# Content

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

Compatibility

HTML comments are invisible in:

• GitHub and GitLab Markdown rendering
• Most documentation sites (Docusaurus, VitePress, etc.)
• VS Code preview
• Any standard Markdown viewer

The comment remains in the raw file but never appears in rendered output.

When to Use HTML Comments vs Frontmatter

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

Quick Examples

Minimal opt-in:

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

Full metadata:

<!-- strayfiles: {"enabled": true, "id": "api-docs-main", "workspaces": ["work", "documentation"], "alias": "API Docs"} -->

With alias (for files with common names):

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

Multiple workspaces:

<!-- strayfiles: {"enabled": true, "workspaces": ["claude-code", "cursor", "ai-tools"]} -->

Sensitive file (local-only):

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

Priority

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