Field Notes

meta

Linking and citation conventions

StatusStableUpdatedSupportsnotes

The wiki uses two link forms for two distinct purposes, and the distinction is enforced by lint.

Wikilinks connect notes within the wiki. The basic forms are a page link, a section link, and a same-page section link. Use double brackets around the target: two opening brackets, the page name or a hash-prefixed section name, and two closing brackets. Section targets use a hash before the heading text.

Wikilinks resolve by filename stem. Section wikilinks resolve by rendered heading text, so section links depend on stable, descriptive headings.

Unresolved page wikilinks — redlinks — are intentional. They are a research queue: concepts that should probably become articles, named things the wiki wants to describe, and open questions awaiting evidence. A redlink does not need its page to exist first; one meaningful relationship is enough to justify the link.

Do not redlink passing phrases, local details, or likely aliases of existing pages.

Pipes change display text for grammar, inflection, or genuinely different display text. They are not for cleaning up title text. Use a pipe when the rendered label needs a different grammatical form than the page name, such as an adjective form of a noun, but not when the label is identical to the page name.

Alias targets

When the alias is the natural text to show, use a canonical-target pipe link: write the real page name first, a pipe character, and the display text after it.

Direct alias targets do not reliably support navigation or diagnostics. The linter rejects them; just fix rewrites them automatically.

Normal Markdown links handle external URLs and files under src/sources/:

[example.com](https://example.com)
[sources/report.pdf](sources/report.pdf)

Links to local evidence are relative to the source document. Because wiki notes live at the top of src/, link local evidence as sources/example.pdf, not src/sources/example.pdf.

Claim-level citations

Frontmatter sources answers which evidence materially informed the note as a whole. Mapping a particular claim to its source is what inline citations are for.

Use a normal inline link when the source name fits naturally into the sentence:

The GDPR requires data minimization.[^gdpr-art-5]

Use a footnote for a consequential factual, legal, numerical, or disputed claim when an inline link would make the prose harder to read:

Swedish private actors face a specific rule
for personal data concerning criminal offences.[^imy-article-10]

[^imy-article-10]: [IMY guidance on criminal-offence data](https://example.com)

Keep the source in frontmatter as well when it materially informs the note as a whole. Do not footnote common knowledge, the note’s own reasoning, or every sentence in a paragraph supported by the same source.

The rendered wiki sets each footnote in the margin beside the sentence it supports, where a reader takes it in without clicking. A publisher name over a URL is read there as the whole reference, so it has to carry enough to identify the work and judge its authority: who is speaking, what the work is and what carries it, when it was published, where inside it the passage sits, and how to reach it — link, DOI, and the saved copy the wiki holds.

Leave out an element the wiki cannot establish rather than guessing at it, and record what was actually consulted when that bounds the citation: an abstract rather than the full text, a press release rather than the judgment.

Add what the reference alone cannot carry, where there is something to add: the holding a case turned on, the sample a study drew, or how the source stands against another cited nearby. A footnote citing a source note opens with the wikilink and puts the work’s own identification after it.

Asides in the margin

Citation is the common use of the margin, not the only one. A footnote can also record how a figure was counted, gloss a term the sentence should not stop for, name a divergent account in the literature, or hold a peripheral fact the sentence has no room for.

Two things stay out of it. A caveat that would not survive on its own is not rescued by demotion to smaller type. And anything a reader must not skip belongs in a callout instead: the margin is skippable by construction, and a narrow viewport does not show it at all.

Keep footnotes short. They stack down the margin, so a long one pushes the notes after it away from the sentences they answer to.

When a citation supports a sentence

A citation is a claim that the source supports the adjacent sentence, not merely that the source is relevant to the paragraph’s topic. When editing a passage that already carries a citation, re-read the sentence the citation is attached to after every edit that changes what the sentence argues. A source found for one claim commonly gets kept when the surrounding sentence is rewritten to argue something adjacent; re-verify that the citation still supports the sentence it is now attached to, and move or drop it when it does not.

The wiki’s link structure is navigable in several ways:

  • just wanted lists unresolved page wikilinks with source contexts.
  • just links reports the resolved link graph: orphans, unreferenced notes, dead ends, and the most-linked notes.
  • just clusters partitions notes into link neighborhoods and lists bridge links between them.
  • The generated Graphs page renders the complete wikilink graph as an interactive force simulation.

These tools make the link graph a discovery surface: notes accumulate backlinks as other notes grow, and a well-linked note is discoverable from multiple directions.

This note cites no sources of its own.

Working out connections…