Adjacent files
Source files kept beside a document, served as-is, quoted from the note that explains them.
- #authoring
- #assets
- #filesystem
An entry is a directory, so the code a note is about can live in it as a real file. This is the point of the whole arrangement: the snippet in the document and the file on disk are the same code, and the file can be opened, linted and type-checked like any other.
- README.mdxthis document
- sample-snippet.tsserved as-is
This directory holds sample-snippet.ts. Following that link serves the file itself rather than a page about it.
Quoting the file
A document quotes the part worth reading and titles the panel with the file's name, so a reader knows the snippet is an excerpt of something they can open:
The quote is written by hand. Nothing keeps it in step with the file automatically, so quote the smallest part that carries the point, a signature rather than a body, and the two will not drift.
What belongs here
Anything the note refers to: .ts, .tsx, .js, .json, .py, .sh,
.css, a schema, a config, a diagram. Discovery types each file by extension
and exposes it on the entry's metadata; there is no manifest to update.
What does not belong is anything secret. Discovery is by directory, so a file
beside a document is published with it. A .env, a key, or a dump with real
data in it is public the moment the directory is. Keep those out of content/
entirely rather than relying on nothing linking to them.
Checking it
Validation resolves every asset reference against the filesystem, so a renamed file fails the build at the document that still points at the old name:
Files in this entry
Saved beside the document, and served as-is.
Related entries
Images and figures
How an image beside a document is referenced, captioned, and kept readable in both themes.
File tree
A directory listing with selectable names and real file icons, instead of ASCII art in a code fence.
Typography
Headings and their anchors, inline formatting, blockquotes and rules, as the document surface renders them.