43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
---
|
|
name: obsidian-markdown
|
|
description: Markdown in an Obsidian vault that agents also write — use when an agent writes or edits any .md file in a workspace with a `.obsidian/` folder (notes, READMEs, CONTRIBUTING, AGENTS.md, skills, docs); when someone mentions Obsidian, hard wrap, ragged "poetry" margins, wikilinks, or the vault; when adding a symlink to markdown. Not for Discord or PR text (see grice-maxims).
|
|
---
|
|
|
|
# Markdown for an Obsidian vault agents write in
|
|
|
|
The workspace is an [Obsidian](https://obsidian.md/) vault: a `.obsidian/` folder at its root. Dan reads and edits in Obsidian; agents write the same files from a terminal. Write markdown that reads well in Obsidian and on GitHub, and is easy for an agent to edit.
|
|
|
|
## One line per paragraph
|
|
|
|
Don't hard-wrap prose. A paragraph is one line; so is each list item. Break lines only between blocks: paragraphs, list items, headings, fences.
|
|
|
|
Wrapped paragraphs render with a ragged "poetry" margin in Dan's Obsidian, and they make diffs of a one-word edit reflow a whole paragraph. Code blocks keep their line breaks, of course.
|
|
|
|
When you rewrite a wrapped paragraph, unwrap it. Don't unwrap a whole file you aren't otherwise rewriting: that's a noisy diff in someone else's prose.
|
|
|
|
## Links
|
|
|
|
- Standard markdown links with relative paths: `[the webkeys pattern](docs/webkeys.md)`. Obsidian follows them, and GitHub renders them. `[[wikilinks]]` render only in Obsidian.
|
|
- No spaces in file names, so links need no `%20`.
|
|
- Link text says where the link goes (see hypertext-links).
|
|
|
|
## File names and headings
|
|
|
|
Obsidian shows file names in tabs, the file explorer, and search, so name files for what's in them.
|
|
|
|
Headings show in Obsidian's outline pane: make them say something.
|
|
|
|
## Frontmatter
|
|
|
|
Obsidian shows YAML frontmatter as Properties. Keep it valid YAML: quote values that contain `: ` or start with a special character.
|
|
|
|
## Symlinks
|
|
|
|
From [Obsidian's symlinks page](https://obsidian.md/help/symlinks):
|
|
|
|
> Obsidian ignores any symlink to a parent folder of the vault, or from one folder in the vault to another folder in the same vault.
|
|
|
|
> File symlinks (as opposed to folder symlinks) may work, but aren't officially supported at this time.
|
|
|
|
So a folder symlink inside the vault (`.claude/skills` → `.agents/skills`) is invisible to Obsidian, and that's fine: no duplicates. A file symlink like `AGENTS.md` → `CONTRIBUTING.md` may not show or update in Obsidian. Edit the target, never the link.
|