super-productivity/docs/wiki/0.01-Style-Guide.md

Style Guide

This outlines some of the structure and formatting choices that have been made for these markdown notes. Maintaining compatibility between CommonMark, GitHub-Flavored Markdown, GitHub's built-in Wiki limitations, and Obsidian-Flavored Markdown requires deliberate effort or there is a risk that they cannot be ported to another service with relative ease (eg. another Wiki program, GitHub/Cloudflare pages via a Static Site Generator, etc.)

Many of the limitations below (especially pathing and naming) are due to the way that GitHub's Wiki sanitizes and restructures the notes it receives.

See also: 0.-Meta-Diataxis for an introduction to the documentation framework used as well as 0.00-Wiki-Structure-and-Organization for more details on how to write notes for the wiki.

Flat Structure with Absolute Paths

Nested directories are only reliable if using Wiki-style links. There is no mechanism to prevent duplicate note names if they are in different subdirectories because GitHub will collapse Dir1/note.md and Dir2/note.md into a single note with the other becoming inaccessible.

Therefore: all notes should be "flat" inside docs/wiki excepting images and other files which can be located in a subdirectory since GitHub does not need to render these as distinct pages. Storing in docs/wiki/assets helps keep the root of docs/wiki somewhat cleaner.

vault/
├─ 1.01-First-Steps.md
├─ 2.09-Configure-Sync-Backend.md
│
├─ assets/
│  ├─ 1.01-First-Steps-start-time-tracking.png
│  ├─ diagrams/
│     ├─ flow.png

Wiki-style Links

Markdown Links are verbose and awkward for others to type. If the links were auto-generated then it would not be a problem. This forces Wiki-style links for notes and images. The only notable difference between GitHub and Obsidian is that the use of ! is not needed for GitHub.

Both of these are valid:
Root: [[image-at-root.png]]
Nested Image: [[images/image.png]]

As mentioned above, nesting the images cuts down on clutter so that is preferred.

Aliases

Links such as [[9.Test-Note|Test Note]] will result in a path be rendered as a URL such as ../wiki/Test-Note and will not resolve to anything. Do not use this syntax.

Linting

There is a GitHub Action to lint all markdown with pymarkdownlnt. If able, invoke pymarkdownlnt --disable-rules line-length scan --recurse ./docs/wiki on all files before submitting a PR. On Arch it requires only pipx install pymarkdownlnt. Ideally, configure as a pre-commit hook to ensure every commit will pass CI.

This simple hook should suffice:

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/sh
set -eu

pymarkdownlnt --disable-rules line-length scan "docs/wiki"
EOF

chmod +x .git/hooks/pre-commit

Additional linting can be done using Obsidian with the "Linter" plugin. See 2.10-Configure-Obsidian-for-Wiki-Contributions#Plugins for more detail.

Indenting

No tabs.

Two spaces only.

Spaces and Dashes

Replace all spaces with dashes on the Obsidian side. GitHub will do this automatically and it is better to do this deliberately to avoid potential note conflicts such as API Reference.md and API-Reference.md. If detected by GitHub, one of them will be silently dropped or at least be made inaccessible through regular links.

Anchor Links

Similar to notes, they are flat within a single note. Spaces become dashes and upper case becomes lower case too. The notes would become pretty ugly if I tried to maintain unique, flat references for every single sub-header. If there were a way to validate headings to prevent duplication then it would be a bit easier. Use them with care and prefer instead to keep notes shorter to avoid the need for deeply nested references entirely.