# 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.

```txt
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:

```md
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
```

### Excluding Certain Notes from the H1 Rule

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):

```md
<!-- 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.

## 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.
