Tags Configuration

Configuring Tags

Tags help you categorize notes across workspaces. Configure auto-tagging via glob patterns in strayfiles.toml.

Basic Tag Configuration

[tags.urgent]
description = "High priority items"
include = ["**/urgent/**", "**/critical/**"]
color = "#EF4444"
icon = "alert"

[tags.reference]
description = "Reference documentation"
include = ["**/reference/**", "**/docs/**"]
exclude = ["**/drafts/**"]
color = "#10B981"

Tag Properties

Property	Type	Description
description	string	Human-readable description
include	array	Glob patterns for auto-assignment
exclude	array	Glob patterns to exclude (overrides include)
color	string	Hex color for UI display
icon	string	Icon name or emoji

Auto-Tagging with Globs

Files matching include patterns are automatically tagged:

[tags.api]
include = ["**/api/**", "**/endpoints/**"]

[tags.tests]
include = ["**/*_test.md", "**/*_spec.md", "**/tests/**"]

[tags.archive]
include = ["**/archive/**", "**/old/**"]
exclude = ["**/archive/keep/**"]

Frontmatter Tags

You can also assign tags directly in frontmatter:

---
strayfiles:
  enabled: true
  tags: [urgent, api, reviewed]
---

Union Merge Semantics

Tags are assigned from both config patterns and frontmatter:

Example:

Config:

[tags.docs]
include = ["**/docs/**"]

File at projects/docs/api.md:

---
strayfiles:
  tags: [api, reference]
---

Result: Note has tags docs (from config), api, and reference (from frontmatter).

Tag Colors

Use hex colors for visual organization:

[tags.urgent]
color = "#EF4444"  # Red

[tags.in-progress]
color = "#F59E0B"  # Amber

[tags.done]
color = "#10B981"  # Green

[tags.idea]
color = "#8B5CF6"  # Purple

Naming Rules

• Max length: 100 characters
• Allowed characters: alphanumeric characters, hyphens, and underscores only. No spaces (unlike workspaces, which allow spaces)
• Case-insensitive uniqueness: “Urgent” and “urgent” are considered the same tag — you cannot have both
• Per-note limit: a single note can have at most 50 tags
• Deleting a tag removes all note-tag associations for that tag. Notes themselves are never deleted.

Tips

Project-specific tags:

Different projects can have different tag configurations in their local strayfiles.toml.

Combine with workspaces:

Use tags for cross-cutting concerns (status, type) and workspaces for organizational grouping (project, team).