mirror of
https://github.com/johannesjo/super-productivity.git
synced 2026-07-18 17:05:48 +00:00
c2b18683d8
* docs(wiki): add new Quickstart to help with using Sync There is a slew of notes that try to explain or show this so a Quickstart can help bring everything into one place. * docs(wiki): combine "First Steps" into single note with relevant links * docs(wiki): update index notes * docs(wiki): fix remaining broken external links * docs(wiki): add core developer How-To guides to orient first-time devs The majority of the documentation is currently spread across several files ins "docs/" and READMEs. Over time these can be consolidated into the wiki while retaining the common CONTRIBUTING.md as a valid entry point. * docs(wiki): add basic guides for plugins and issue integration As with the core development docs, there is too much to add here right now. These notes will serve as a simple entry to other resources. * docs(wiki): add basic reference note for theming * docs(wiki): add basic Translation guide * docs(wiki): rename Theming and linting to clean up headings * docs(wiki): add heading lint exception for GH-specific nav pages; rework sidebar and index pages Sidebar should be a quick-access for the more common topics grouped thematically with the X.00 notes simply enumerating all the notes where appropriate.
86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# 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.
|