How this wiki is organised¶
Rules for me, so that importing the rest of the vault does not turn this into a folder called "stuff" with 400 files in it.
One note, one thing¶
A note answers one question or documents one procedure. If a note needs an "and" in its title, it is two notes. The title is the words I would type into the search box in six months — "Upgrading Nextcloud Manually", not "Nextcloud".
The file name is the title. If a note's first # heading says something other
than its file name, the sidebar shows the heading, not the name, which is how
"Git Instructions" ended up labelled "Branching". Either make them match, or
put a title in the frontmatter:
Frontmatter titles also fix the browser tab and the search results, so they are the better fix of the two.
Folders are subjects, and only go two deep¶
Top-level folders are broad subject areas: Programming, Game Development,
Graphics, Maths, Hardware, Linux, Recipes, Health. One level of subfolder below that for a topic with
enough notes to need it — Maths/Linear Algebra. Never three.
A folder earns its existence at about four notes. Below that the notes live in the parent folder. Moving a note later is cheap; the only cost is the URL, and nothing outside the wiki links to it anyway.
Anything that does not fit a subject is a sign the subject is missing, not that the note needs a new folder of its own.
Every folder has an index.md¶
Each folder's index.md gets a one-line description and a
<!-- wiki:children --> marker, which the build expands into the list of notes
and subsections inside it. That one line is also what the front page shows next
to the section name, so it is worth writing properly.
This means a new folder needs exactly one file written by hand, and never needs updating as notes are added.
Where new notes go¶
Unfinished notes go in _drafts/, or are named something.draft.md. Those are
excluded from the build entirely, so they can be as rough as they like and they
are not published by the hourly deploy. Notes named *.private.md are excluded
the same way.
A note leaves _drafts/ when it is useful to someone who is not me.
To keep a finished note out of the sidebar but still published at its URL, add
this to the folder's .nav.yml instead:
Link notes to each other¶
Use Obsidian [[wikilinks]]; the build resolves them. A note nothing links to
and that links to nothing is usually a note filed in the wrong place — that is
the cheapest signal available that the structure is drifting.
Tags, when folders are not enough¶
Folders are one axis, and some things cut across them: arch, z80,
high-protein. Those are tags, in the frontmatter, which is exactly where
Obsidian puts them:
Tags are not switched on in the wiki build yet - see the commented-out tags
plugin in mkdocs.yml. Tag notes as they are written and turning it on later
is free; retro-tagging 400 notes is not.
Keep the tag list short and reuse it. Two tags that mean the same thing are worse than no tags.
The sidebar¶
Order, section names and visibility come from .nav.yml files in the vault,
one per folder, and only where the default - alphabetical, index first - is
wrong. See .nav.yml in the root of this folder for the syntax, or the
plugin docs.