docs/wiki/0.01-Style-Guide.md
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.
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
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.
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.
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
The linter rule MD041 (first line in file should be a top-level heading) can be disabled for specific notes so they are not required to start with an H1.
Per-note: Add this HTML comment as the first line of the note (no blank line before it):
<!-- pyml disable md041 -->
The pragma is stripped before parsing, so it does not affect rendering. Only that file is exempt from MD041.
Whole wiki: To turn off the H1 requirement for all wiki notes, add md041 to the --disable-rules list in .github/workflows/wiki-sync.yml (e.g. --disable-rules line-length,no-inline-html,md041). No per-note pragmas are needed.
Additional linting can be done using Obsidian with the "Linter" plugin. See [[2.10-Configure-Obsidian-for-Wiki-Contributions#Plugins]] for more detail.
No tabs.
Two spaces only.
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.
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.