Version 1 of 1 · · razie · in person · Current version

name
d3-f-tags
description
Tags — the frontmatter tags line, the few tags that change what d2 does (ephemeral, notlisted, inherited, spec), conventions, finding things by tag. Get skills only from /api/v2/skills/d3.
feature
ttag
concepts
[tag]
tags
#skill #feature #d3skill #wip

d3-f-tags

Intro

Tags on topics and files.

Tags are flat words on a topic's frontmatter tags: line that group and find topics and files. A few behaviour tags change what d2 does with a topic. Topics are d3-f-topics; search is d3-f-search. Spec: Spec › topic-tags.

Essentials

  • R-tags-1 Tags go on the frontmatter tags: line, comma-separated, flat lower-case words — NEVER nested (mining/gold).
  • R-tags-2 Tag what you write, reusing the project's tags before inventing one.
  • R-tags-3 NEVER add or remove a behaviour tag (ephemeral, notlisted, inherited, spec) unless your person or your task says so.

Concepts

tag

A flat word grouping topics and files; compared ignoring case. Objects have no tags: find them by their fields. Also called: label, #tag. Behaviour tags (the only ones that change what d2 does): ephemeral (no history; Dismiss deletes it for good), notlisted (out of the Docs list and search, still opens by link), inherited (on base d2: every project inherits it), spec (on a Settings: topic: compiled like a Spec topic). Every other tag only groups and finds.

tag_write

  • Summary: tag what you write; reuse existing tags; follow conventions.
  • When: writing or creating a topic.
  • Needs: the project's tags in use.
  • Call: frontmatter tags: mining, gold · existing tags: GET /api/v2/topics (each topic's tags).
  • Rules: R-tags-1, R-tags-2. Conventions: skill, feature / skill, <role> on skills; report, <role> (+ ephemeral for a one-off) on reports; wip on working topics that aren't a final document.
  • Errors: a tag with a / or spaces isn't one tag → rewrite it as flat words.
  • Gotchas: —

tag_find

  • Summary: find topics (and files) by tag.
  • When: looking for everything on a subject.
  • Needs: the tag.
  • Call: GET /api/v2/topics?tag=gold Also: with words: GET /api/v2/search?q=%23gold%20nevada (tagged topics that also mention nevada, and tagged files).
  • Rules: People filter the wiki with /topics?tag=gold (the Docs list) and search with #gold. Files take the same words (?tags= on upload, d3-f-cdn › file_store), so one tag finds notes and images together.
  • Errors: —
  • Gotchas: Thoughts keep their own tags, toggled include → exclude → off (d3-f-thoughts).

tag_setBehaviour

  • Summary: behaviour tags only on your person's or task's word.
  • When: your person or task asks for a topic to be ephemeral, unlisted, inherited or compiled as spec.
  • Needs: their word.
  • Call: edit the tags: line (d3-f-drafts › draft_save).
  • Rules: R-tags-3 — it changes who sees the topic or whether its history is kept. A new tag that should do something is a spec change first: added to Spec's topic tags list with its tests, before it's built.
  • Errors: a behaviour tag you weren't asked to change → put it back and tell your person.
  • Gotchas: —

tag_diagnose

  • Summary: a topic hidden, history-less or everywhere — check its behaviour tags.
  • When: a topic vanishes or doesn't show where expected.
  • Needs: the topic (and the base topic it inherits, if any).
  • Call: read its tags: line (d3-f-topics › topic_read).
  • Rules: Missing from Docs or search but opens by link → notlisted (its own, or on the base topic it inherits). No history, or gone after Dismiss → ephemeral. A base page every project shows (Help, a skill, a style) → inherited on base d2; a project's own topic of the same name overrides it. Reports never show in search, tagged or not.
  • Errors: —
  • Gotchas: —

Errors

  • Tag with / or spaces — not one tag → rewrite as flat words. see #tag_write
  • Behaviour tag changed unasked — put it back and tell your person. see #tag_setBehaviour