Writing notes: tags, people, and links

What is a note

Tags decide where a note starts and ends:

• A heading with tags of its own is a note, with every untagged heading under it, down to the next heading with tags of its own, which is a note of its own and also carries the tags above it. In # ADR-001 #decision with untagged ## Context and ## Consequences under it, the ADR is one note; a ## Decision #decision/accepted among them would be a second.
• A note tagged in its front matter is one note, apart from any heading in it with tags of its own.
• Where no tag reaches, such as a daily note with no tags, each heading is a note, so a search lands on the right section.
• A task is always an entry of its own, and it carries the tags of the headings above it.

A search lists notes: a word written under ## Context finds the ADR, and the ADR’s card shows its whole text. Home’s and Stats’ Notes, a tag’s count, Related Notes, and the Notes Graph count notes the same way.

Markdown format

Deckard recognizes ATX headings, unordered checklist items, # tags, @ people, and [[Wiki links]]. Tag matching is case-insensitive.

Note boundaries. deckard.noteBoundaries sets where one note ends and the next begins:

• Under heading, a prose tag stays on its line; it is not added to the heading, and it counts for the note that holds the heading. A tag on a heading is inherited by everything nested under it.
• A tagged line with no heading above it stays a note under every setting.
• Consecutive tagged prose lines are grouped; under marked, one marker marks the group.
• A task is its own entry under every setting.
• Changing the setting reindexes the workspace automatically, and writes nothing to your notes.

Citations. A Pandoc citation in brackets, such as [@smith2020; @lee2019, p. 33] or [see @kim2021], names no person, so citation keys never become people or offer to merge as tags that look alike. A Dataview field such as [assignee:: @dana] and link text such as [@sam](…) still name their person.

Links. A [[link]] names a note by its file name without .md, or by any name in its aliases: front matter, such as aliases: [Atlas Program, AP]. [[Atlas.md]] works too, and opens Atlas. A name two notes share opens neither. A link in fenced code or inline code, such as `[[Atlas]]`, is an example: it links nothing. A link to an image or other attachment, such as ![[diagram.png]], is not a note, so it is never a missing one.

Markdown links count too. A relative link such as [the decision](https://github.com/doctorallen/deckard/blob/master/docs/adr/0042.md#decision-record), the kind GitHub and MkDocs render, links its note just as [[0042]] would: it shows in Linked from, the Notes Graph, Related Notes, and Stats, and a #fragment written as a heading’s slug finds that heading. A link to a web page, to a path from the root, or to a file outside your notes links no note, and is never reported as a missing one. Deckard writes [[links]] when it makes one, such as from a mention; deckard.links.style set to markdown writes [Atlas](projects/Atlas.md) instead. Renaming a note rewrites its [[links]]; VS Code’s own markdown.updateLinksOnFileMove.enabled rewrites Markdown links.

After #, a link can name a heading, as [[Check-in#Vendor review]] does, or one line, as [[Check-in#^lift-slip]] does. A line is named by the ^marker at its end (Obsidian block-reference style):

## Vendor review
The lift survey slipped because the contractor never confirmed. ^lift-slip
- [ ] Chase the contract @dana ^chase

• A marker is the last thing on its line, separated from the text. Markers in fenced code are ignored; when a note repeats one, the first wins.
• Typing [[Check-in#^ completes that note’s markers, each shown with its line.
• Following the link opens the note at that line; hovering previews it.
• Deckard reads markers but never writes them.

Embeds

Write ![[Note]] on a line of its own and VS Code’s Markdown preview draws that note there:

• An embed names its note as a link does. A name two notes share reads neither; a name no note has says so.
• ![[…]] inside a sentence stays as typed. ![[diagram.png]] is drawn as an image on the note page; the preview leaves it and other attachments alone.
• Embeds nest up to three deep.
• An embed inside fenced code is left as code.

Reading a note as a page

Deckard: Open Note as Page, also the unicorn button in a note’s title bar and in the editor’s Deckard right-click menu, opens the note on a page of its own, drawn in Deckard’s theme with the parts only Deckard understands working:

• Tags open their page, and [[links]] open the note they name on the same page. ‹ and ›, or the mouse’s back and forward buttons, step through the notes it has shown.
• Tasks have working boxes, with Undo in the message, and steps sit under their task.
• Query blocks draw their results live, a list or a table, and each row opens what it lists. Embeds draw what they name, with a title that opens it.
• Images, ![alt](img/flow.png) or ![[flow.png]], are drawn at the page’s width; select one to see it at full size. Deckard reads each from beside the note, or from the workspace folder’s top, and draws nothing from the web or from outside the workspace folder; an image it cannot draw says why, such as one larger than 4 MB.
• Front matter names what Deckard reads as a reader would: About for describes, Filed under for up, Also called for aliases.
• Front matter is listed under the page’s bar, one property to a line, a tag among the values a button. A note whose front matter says type:, such as a decision, lists its fields there, then Edit fields…, which opens the form that edits them, as ⋯ does; a hub note’s fields are shown on its tag’s page, since a hub note opens there. A note under a hub shows where it sits.
• Progress. A note with tasks shows a Tasks bar under its title: how many of its own tasks are done, how many are overdue, and when the next is due, steps aside. A hub note shows a bar above it too, for every task its tag finds in any note, labeled by what the tag names, such as Project, Team, or Person, with a button to the tag’s page.
• Linked from lists the notes that link here, each with the lines that do.
• The bar is laid out as every Deckard page’s: DECKARD ▾, the note’s folder, and its title at the left; ‹ ›, Open in Editor, and ⋯ at the right. ⋯ holds Open Related Notes, Open Notes Graph Around This Note, Pin Note to Home or Unpin, and Park Note or Unpark, then Theme…, Zen, Page width and Help on this page.
• Open in Editor opens the note at the line in view, and a double-click on a paragraph, a task, or a block opens the editor at its line. Shift-click a link to open its note in the editor instead.

A hub note opens as its tag’s search page instead, which draws the note at its top with the tag’s progress, notes, and tasks under it; the editor still opens its Markdown. The page is one tab, reused for each note as VS Code’s preview tab is, and it is reopened on the note it showed after a reload. It follows each save. The unicorn button opens it in the note’s own editor group, in front of the note’s editor, as Markdown’s Open Preview does; Open in Editor switches back. While the page is in front, the Context view’s Related Notes follows the note it shows, as it follows a note in the editor, and picks the entry at the line the page was opened at.

Opening every note there. Set deckard.openNotesIn to page and a note or task opened from any Deckard page opens on the note page, scrolled to its line, which is marked for a moment: a search page’s cards and tasks, Related Notes, Home, the Task Board, the calendars, Stats, the Notes Graph, Find, the Hubs view, and the breadcrumb lens. The default, editor, opens them in the editor as before.

The other way, one key away. Whichever the setting says, Shift-click a note or a task to open it the other way, and Shift+Enter from the keyboard, Find included. Cmd/Ctrl+Shift-click opens it the other way beside the page. A tree row and a lens cannot tell which keys were held, so the Hubs view’s notes, hub notes included, offer the other way on their right-click menu, Open in Editor or Open as Page. A link followed in the editor, the Tasks view, and the Outline always stay in the editor.

Copying a note for elsewhere

Embeds, query blocks, and [[links]] mean something only to Deckard. Deckard: Copy as Plain Markdown, also in the editor’s Deckard right-click menu, copies the note, or what is selected in it, written out for a chat, an email, or a pull request:

• an embed becomes the text it names, three deep;
• a query block becomes its results as they stand: a list of notes and tasks, or Markdown tables for view=table;
• a [[link]] becomes its words, [[Atlas#Decision]] as Atlas › Decision and [[Atlas|the plan]] as the plan;
• front matter and ^markers are left out, and other code is left as written.

Tags and people

By default, use @ for people and namespaced # tags for workspace entities:

# Project Atlas #project/atlas
Met with @alex-smith about [[Q3 planning]].

- [ ] Send the proposal by 2026-09-12 #project/atlas

• #project/atlas, #topic/leadership, #org/acme, and #meeting/q3-planning appear as entity hubs.
• Any other namespaced tag, such as #management/performance, creates a namespace and appears as Management: Performance.
• Unnamespaced tags such as #follow-up work too. All tags appear in Home’s Tags tab.
• A tag’s name is letters and digits of any language, _, and -, so #café and #日本 are tags. A tag starts a word: the # in café#latte or in a web address such as https://example.com/#install is not one.
• @alex and #alex are different tags.
• Namespace aliases map a custom namespace to any built-in or custom namespace. You can change the people marker; @name then becomes a lightweight tag.

Front matter adds entity context to every heading and task in a note:

---
project: atlas
people: [alex-smith]
topics:
  - leadership
---

people/person maps to @person; projects, topics, organizations, and meetings map to their typed # tags. These are Cmd/Ctrl-clickable like inline tags.

Front matter can also hold a type’s fields: a hub note’s lead: "@alex-rivera", or an incident’s severity: sev1 in a note that says type: incident. A note in your Types folder says which fields a kind of thing has, and Deckard then shows them as a table, on the note’s page, and in hovers, and answers questions from them; see Types and fields.

Deckard: Move Inline Tags to Front Matter moves the note’s explicit tags into plural front-matter fields, merging existing values and keeping other YAML. Use it only for tags that belong to the whole note.

Renaming tags. Run Deckard: Rename Tag, right-click a tag on Home, a search page, or Related Notes and choose Rename tag, or hover a tag in the editor and choose Rename. It renames the tag everywhere it is written, leaving ordinary words and fenced code alone. Renaming to an existing tag merges the two; see Merging tags. Enter a complete tag such as #management/new-name, or only a name to keep the marker and namespace. The box starts from the old name and previews the result, such as Merges into #project/atlas (42 entries).

Syntax rules:

• Headings use the ATX form # Heading through ###### Heading. Optional closing hashes are removed from the title.
• Tasks use -, *, or + followed by [ ] for open or [x]/[X] for completed.
• A task inherits tags from its nearest heading and adds tags on its own line.
• Tag names start with a letter or number and can contain letters, numbers, _, -, and / namespace segments.
• A # in fenced code, inline code such as `#not-a-tag`, or links such as [[#Heading]] or [text](#anchor) is never a tag.
• Numeric-only hash tokens such as #2026 are not tags. Numeric @ tags such as @2026 are.
• Associated tags: tags written together on one heading, task, or tagged line are suggested in Related Notes as belonging together, Front-matter and inherited tags never create associations alone.

# Launch plan #project/atlas

## Next steps #topic/planning

- [ ] Review the brief #topic/writing
- [x] Send the update @alex-smith

Terms

Work notes are full of short terms: UAT, NDF, RATES-UAT. Deckard reads where each was defined, and says what it means wherever it is written.

• A term is two to six capitals and digits with a letter in them, or up to twelve with hyphens between its parts, used in at least three entries: a heading and the lines under it, or a note’s text above its first heading. Words in capitals that are no term, such as OK, TODO, AM, US, FYI, and month and day names, are left out, as are times and quantities such as 10AM, 24H, and 5K, and so is anything in code, a link (its words as well as where it goes), a web address, a tag, or front matter, and every word of a line written all in capitals.
• A term note defines a term: a note whose front matter says type: term and term: NDF, or whose title is the term, and whose first paragraph is what it means. It wins over anything written elsewhere. A workspace needs no Term type for Deckard to read one.
• Inline, a term is defined where it is written as NDF (non-deliverable forward) or non-deliverable forward (NDF), else as NDF means words (or stands for), else as a line NDF: words, the first time by date of the first of those found. The words in parentheses, or before them, count only when they spell the term’s letters: each letter starts a word, in order, with small words such as of and and skipped. A line NDF: words counts when its words spell the letters, or are three words or more and the line is no list item, or the term is in bold as a glossary writes it (- **NDF**: words), so a status such as - UAT: blocked on data defines nothing.
• Hover a defined term in any note for NDF · non-deliverable forward · 4 entries, where it was defined, Defined Tue, Mar 3 in FX recon kickoff: “…”, or From NDF.md, and Open definition, Find uses (a search for the term as a word, text = NDF), and, for an inline definition, Make a term note, which opens New Note from Type…’s form for a Term with the term and its words filled in.
• A faint dotted line marks each defined term (deckard.editor.termUnderline); Zen hides it, never the hover. Its color is deckard.termUnderline.
• Stats lists the terms used but never defined, and those defined; Find answers NDF or what is NDF with its definition; and assistants can ask deckard_define_term (AI assistants).

Editor assistance

Presets. Deckard: Choose Editor Preset… sets how much of what follows Deckard draws: Full, all of it; Tasks, the task hints and problem reports, without link counts, mention lenses, or breadcrumbs; Writing, the / menu, hover previews, faint task details, and reports of broken links, embeds, and repeat rules; Off, none of it. Each deckard.editor.* setting below follows the preset while you leave it unset; one you set yourself, on or off, overrides it.

• Title bar: Deckard’s button opens Deckard: Note Actions…, and the unicorn beside it opens the note as a page. While the daily note’s own lens is off (the Writing and Off presets, or deckard.editor.dailyNoteActions set off), a daily note also has ‹ and › for the previous and next daily notes; otherwise the lens on its first line has them. Right-click the title bar to hide any of them.
• Right-click in a note for a Deckard submenu, which lists what Deckard: Note Actions… lists, in the same order: the task on the line (Toggle Task Done, Edit Task, Set Task Status…, Break into Steps…) and Add Task; the heading (Rename Heading, Extract Heading, Tag Heading with a Person or Project…, Focus Section); the note (Open Note as Page, Open Related Notes, Open Notes Graph Around This Note, Move to…, Copy as Plain Markdown, Move Inline Tags to Front Matter); then Pin or Unpin, and Park or Unpark. A note page’s ⋯ lists the ones that work away from the editor: Related Notes, the Notes Graph, Pin or Unpin, and Park or Unpark.
• Theme colors: in any Markdown file, wiki links, an embed’s !, task dates (📅 2026-10-02, [due:: 2026-10-02]), repeat rules, priorities, Dataview keys, and a trailing ^block-id use your theme’s colors. To change one, add a rule to editor.tokenColorCustomizations, for example { "textMateRules": [{ "scope": "constant.numeric.date.deckard", "settings": { "foreground": "#7aa2f7" } }] }. Scopes end in .deckard, such as constant.numeric.date.due.deckard, string.other.repeat.deckard, and meta.link.wiki.deckard.
• Task metadata (dates, priority, repeat rule, ids, person) and any ^block-id are dimmed (deckard.editor.dimTaskMetadata). An overdue task shows its due date in the overdue color and overdue 5 days at the line’s end; one due today says due today; one more than 30 days overdue (deckard.tasks.needsNewDateAfterDays) says needs a new date (deckard.editor.taskDueHints). Change the colors in workbench.colorCustomizations as deckard.overdueForeground and deckard.taskHintForeground.
• Terms: a short term with a definition, such as NDF, has a faint dotted line, and hovering it says what it means and where it was defined. See Terms. deckard.editor.termUnderline turns the line off.
• Promises: in today’s daily note, a line naming one person and a day to come, such as @sam says the fix lands by Friday, has its day underlined, and its lens and lightbulb track it as a waiting task under the line. See Promises in today’s note. deckard.editor.trackPromises turns this off.
• Unreadable repeat rules are marked on open tasks. The lightbulb offers up to three readable rules. deckard.editor.repeatDiagnostics turns this off.
• Word count is in the status bar: see Status bar and reminders.
• Tags are clickable: Cmd/Ctrl-click opens its page, and the hover has Rename. Tags on every line are handled, headings’ and others’ alike.
• Tag completion: typing # or @ offers indexed tags with entry counts, ignoring fenced code except a deckard query block.
• The / menu: type / alone at the start of a line for what to write there: Task, Heading 1 to 3, lists, Quote, Divider, Link to a note and Embed a note (which open the note suggestions), Today’s note, Today’s date, a Query block, a Notes table or a Tasks table, and each template in your templates folder. A template is written with the note’s title, today’s date, and the time filled in, and each {ask:Question} it holds is a tab stop that reads the question until you type over it. Keep typing to narrow the list: /tab finds the tables. deckard.editor.slashMenu turns it off.
• Task metadata completion: typing / after a space in a task offers due dates, priorities, repeat rules, and dependencies. See Typing metadata.
• Link completion: inside [[, notes are offered as Find ranks them. After [[Note#, that note’s headings are offered; [[# offers this note’s; [[##words searches every note’s headings. A day in words, such as [[next fri, offers that day’s note, [[2026-09-26]].
• Reference counts sit above a note’s lines. The first line shows Linked from N notes. Each heading shows N references and N open tasks, and a tagged heading N entries share a tag, which opens Related Notes. Other counts list in the references peek. deckard.editor.referenceCounts set to false hides them.
• Hovering a [[Wiki link]] previews the note or section and says how many notes link to it.
• Link problems: a [[link]] to a missing note gets a Create note quick fix, and a name several notes share is a warning (deckard.editor.linkDiagnostics). The same setting marks a type’s field whose value names nothing or does not fit its kind.
• Task dependencies for a task using ⛔ or 🆔: Waiting on N open tasks and Blocks N open tasks. A ⛔ name no task carries reads No task has 🆔 name. deckard.editor.taskDependencies turns these off.
• Daily notes show ‹ 2026-09-21 and 2026-09-23 › on their first line. Today’s note also offers Carry in N unfinished tasks, which runs Deckard: Roll Unfinished Tasks Forward. See Daily notes. deckard.editor.dailyNoteActions turns these off.
• Broken embeds say why above their line, such as Embed: Atlas has no heading “Decision” or Embed: Nothing in Atlas is marked ^choice. deckard.editor.embedProblems turns these off.
• Problems: when something about a note is wrong, its first line has one lens that counts it, such as 2 missing · 1 ambiguous · 4 unlinked: links that name no note, links that name a note several notes share, and mentions, other notes that write its title or an alias as plain text without a link. With one kind of problem, selecting the lens fixes it: it creates a note in your notes folder for each missing name (a shared name is not created, and when every broken link names a shared one, it shows them instead), or it turns each mention into a [[link]], previewed and undoable. With both kinds, it lists each fix: Show broken links, Create missing notes, Show unlinked mentions, and Link mentions. In a typed note it also counts the fields whose values name nothing, 2 unresolved, and other field problems, 1 field problem; Show field problems lists them in the references view, each offering its fixes. Names under three characters, and names another note also uses, are not looked for as mentions, and a note that cannot be opened is left as it is. The Context sidebar’s Mentioned without a link lists each mention with its own Link, and Link all; see Connections. deckard.editor.linkProblems counts broken links and deckard.editor.unlinkedMentions counts mentions.
• Step progress: a task with steps has a lens above it with a bar of how many are done and the next one, ███░░░░░░░ Steps 1/3 done (33%) · next: Pack the rain shells, which goes to that step. deckard.editor.stepProgress turns it off.
• Breadcrumbs: a note under a hub says where it sits on its first line, such as Projects › Atlas › Vendor review, which opens the note above it; see the Hubs view. deckard.editor.breadcrumbs turns them off.

• Hub progress: a hub note’s first line says how far along the tasks of the tag it describes are, such as Progress: 2/6 done (33%) · 1 overdue · next due in 3 days, which opens the tag’s page. A typed row’s leads with its type and first relation, **Person · Payments

  1/3 done (33%)**. deckard.editor.hubProgress turns this off.

• Hovering a tag shows its note and task counts, its hub note, its five most recently updated entries, Open overview, and Rename. A typed tag, or a link to a typed note, also names its type, its relations, and how to reach it. deckard.editor.hoverPreviews set to false turns previews off.

File this

Facts about teams and people land in today’s note. File this, on a line’s lightbulb (Cmd+. or Ctrl+.), carries a fact where it belongs. On - @priya-natarajan now leads #team/fx, under ## Org news in 2026-10-14.md, it offers:

• Set FX’s lead to Priya Natarajan (was Alex Rivera), first, when the line says what a type’s field holds in one of the phrases its Words column lists, such as leads for a team’s lead. The row before the phrase gets the value after it, or, when the field is the other row’s type’s, the other way round: @alex-rivera moved to #team/rates sets Alex’s team. A Person field takes a person, a relation a row of its type, and a select one of its options written after the phrase. The value is written in the row’s hub note’s front matter, that key alone; a field that holds several gets it added. A row with no hub note gets one, as Create hub note writes it.
• Add this line to FX’s notes, and the same for each other tag on the line that has a hub note, up to four. The line is copied, its list mark and box aside, as the last item of the hub’s Notes list (a heading at any level, made at the end as ## Notes when the hub has none): - 2026-10-14: @priya-natarajan now leads #team/fx ([[2026-10-14#Org news]]). The date is the daily note’s day, or today; the link is to the line’s heading, written as deckard.links.style says (Settings). The line itself stays where it is.
• File under…, which picks any heading, as Move to… does, and copies the line there the same way.

Each is one write, with Undo in its message and in Deckard: Undo Last Change. A line in a hub note offers no filing: it is already there.

Templates

Put Markdown files in a templates folder at the workspace root, or the folder deckard.templatesFolder names, and run Deckard: New Note from Template. Choose a template and a title; Deckard creates the note in your notes folder and opens it. The templates folder is never indexed. With no templates yet, it offers Create Starter Templates: a meeting, a 1:1, and a decision record, which you can change or delete like any other file.

To write into a specific folder, right-click it in the Explorer and choose Deckard → New Note from Template Here…. The same menu’s Exclude from Deckard leaves the folder out of the index, and Include in Deckard brings it back. Deckard: Create Daily Note and Deckard: New Note from Template are also in File → New File… and on the Welcome page.

Anything else in braces is left as written.

A template named after a tag namespace, such as person.md or project.md, starts every new hub note for that namespace, and one named after a type’s key starts each row Add team… writes. It can use {tag}, and Deckard adds describes: front matter unless the template has its own.

Daily.md, Weekly.md, and Monthly.md start every new daily, weekly, and monthly note, with {date}, {week}, and {month} filled in for the period; see Templates under daily notes.

← Getting started · All topics · Types and fields →