Wikilinks#

Write [[Some Note]] and mdssg finds the note called Some Note, wherever the file happens to sit.

[[Getting Started]]              a link, by name
[[Getting Started|start here]]   with different text
[[Markdown#Tables]]              to a heading inside a note
[[Markdown#Tables|see tables]]   both
![[Markdown#Tables]]             embed the section here

Names, not paths#

A note's identity is its name: the title in its frontmatter, or the filename if it has none. Not its path.

This file lives at content/concepts/wikilinks.md and its URL is /wikilinks/. The concepts/ folder does not appear anywhere in the output. Move the file tomorrow and nothing breaks, because nothing ever pointed at where it was.

The namespace is therefore flat: one name, one note, site-wide. Two notes claiming the same name is a build error:

error: the note name 'index' is claimed by two notes:
  content/projects/index.md
  content/recipes/index.md
Note names are a flat namespace. Give one of them a distinct title, or set an
explicit 'slug' in its frontmatter.

That is deliberately loud. The alternative is picking a winner, which makes every [[Index]] in the site a coin toss that can flip when a file is renamed.

The same check catches something subtler: two files whose names differ only by case. kant.md and Kant.md can coexist on Linux and cannot exist together on Windows. mdssg fails on both, rather than letting you build a site on one machine that cannot be rebuilt on the other.

Aliases#

A note can answer to more than one name:

---
title: Wikilinks
aliases: [Wikilink, Links]
---

Now [[Wikilink]] and [[Links]] both land here. Aliases are matched the same way names are — case-insensitively, and ignoring how accents happen to be encoded, so [[Café]] finds Café whichever of the two Unicode spellings each file used.

Headings#

[[Markdown#Tables]] links to the Tables heading in Markdown and displays as Markdown › Tables.

A heading that does not exist is a warning, not an error, and the link falls back to the top of the note. Renaming a heading is a normal editing act, and it should not be able to stop a site from building.

Embeds#

![[Note]] pulls the whole note in. ![[Note#Section]] pulls in one section, meaning that heading and everything under it up to the next heading at the same depth.

Embedding is expanded when the page is rendered, never when it is parsed, and it stops at three levels deep. Two notes that embed each other produce a visible placeholder rather than a hung build:

circular embed: Some Note

An embed also counts as a link, so it appears in Backlinks and feeds Related Notes. Links inside embedded content belong to the note they came from, not to the note doing the embedding.

When the target does not exist#

It becomes a seed page. That is the next thing to read.