Tags

Tags in Lettuce are inline #tag markers anywhere in a note’s body, plus optional tags: in frontmatter. They’re a complement to wikilinks — wikilinks express this is about that, tags express this belongs to that category.

Inline syntax

This note is about the #lettuce project and uses the #swift language.
We're also tracking it under #status/in-progress.

Tag rules:

The # must be at start-of-line or preceded by whitespace, and immediately followed by a letter.
Allowed body chars: letters, digits, _, -, /. (No # or . inside.)
Case-insensitive — tags are normalized to lowercase, so #Project and #project are the same tag.
The tag stops at the first non-body character, so trailing punctuation (., ,, !, ?, :, ;) is not part of the tag.

Purely numeric markers like #1234 are not treated as tags (the character after # must be a letter), so issue / ticket references stay plain text. C# isn’t a tag either (no whitespace boundary before the #), and # heading is just a Markdown heading.

Frontmatter tags

---
tags: [project, urgent]
---

Equivalent to writing #project #urgent somewhere in the body. Lettuce merges both into a single de-duplicated set per note.

Nested tags

Use / to express hierarchy:

#project/lettuce
#project/lettuce/v1
#status/in-progress

The tag pane shows nested tags in a tree.
notes_by_tag(tag: "project") returns all notes with #project or any #project/* child.
Asking for #project/lettuce does not match #project alone.

Tag pages

When you publish a static site, every tag used in a published note gets a generated page. Each tag page lists the notes carrying that tag — title-sorted, and nested-aware (a parent tag’s page also lists its descendants’ notes). There’s also an overview at tags.html listing every tag with its note count.

In a published site the pages are flat files: a tag’s page is tag-<tag>.html, with any / in a nested tag replaced by _ (so #project/lettuce lives at tag-project_lettuce.html). When you click a tag chip anywhere on the published site it opens that page.

Tag pages are generated directly from the vault — there is no per-tag description or color configuration, and no .lettuce/tags.yml file.

The `#tag IS the link` model

Lettuce intentionally treats #tag as a link — not a separate metadata system. That means:

Tags appear in the link graph (Graph view, “Show tags” toggle).
The tag’s page shows every note using it.
An agent can call notes_by_tag to get the same curated index of related notes.

You’re never forced to choose between “use a tag” and “use a wikilink” — both are tracked, both are queryable.

Tidying up tags

There’s no one-click “rename tag” command. To rename a tag you edit the notes that use it — change the inline #old markers (and any tags: frontmatter entries) to #new. To drop a tag, remove those occurrences.

lint helps here: it flags tag hygiene issues as advisory findings — for example a rare tag that looks like a typo of a common one, surfaced as a Rename #typo → #common? suggestion. Nothing is applied automatically; the suggestion just tells you (or a connected agent) which notes to edit.

Programmatic access

list_tags()
→ every tag in the vault (frontmatter + inline) with note counts

notes_by_tag(tag: "project/lettuce")
→ all notes carrying that tag, or any nested descendant (paginated)

Core concepts/04 Wikilinks, backlinks, and the graph
Publishing/02 The static site — how tag pages get rendered
Recipes/03 Tag curator — an agent that audits your tag taxonomy