2.4 KiB
name, description
| name | description |
|---|---|
| obsidian-markdown | 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 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:
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.