# Obsidian Writer

> Write Obsidian-compatible .md notes and .canvas files. Use when creating notes, knowledge bases, daily logs, project docs, or canvas diagrams for Obsidian vaults. Triggers on "obsidian", "canvas", "vault", "笔记".

- Skill: `dvcrn/obsidian-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/obsidian-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/obsidian-writer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/obsidian-writer

---


# Obsidian Writer

Write .md and .canvas files that render correctly in Obsidian. Output to the vault directory, synced via Git.

## Vault Location

Default: `~/obsidian-vault/` (configurable per request).

## Workflow

1. Write `.md` / `.canvas` files following specs below
2. Git commit + push (agent does this automatically)
3. User's Mac Mini pulls → syncs to iCloud → Obsidian reads

## Markdown — Obsidian-Specific Syntax

Standard Markdown (headings, bold, lists, code blocks) is assumed known. Only Obsidian extensions below:

### Properties (Frontmatter)

Must be the **very first thing** in the file:

```yaml
---
tags:
  - finance/macro
  - iran-war
aliases:
  - 伊朗战争概览
cssclasses:
  - wide-page
created: 2026-03-10
---
```

Reserved keys: `tags`, `aliases`, `cssclasses`, `publish`, `permalink`, `description`.

### Internal Links (Wikilinks)

```markdown
[[Note Name]]                    # link to note
[[Note Name|Display Text]]      # custom display
[[Note Name#Heading]]            # link to heading
[[Note Name#^block-id]]          # link to block
```

### Block References

Add `^block-id` at end of any paragraph/list item:

```markdown
This is an important paragraph. ^key-insight

- List item ^item-ref
```

Then link: `[[Note Name#^key-insight]]`

Block IDs: lowercase alphanumeric + dashes only.

### Embeds

```markdown
![[Note Name]]                   # embed entire note
![[Note Name#Heading]]           # embed section
![[image.png]]                   # embed image
![[image.png|300]]               # resize width 300px
![[image.png|300x200]]           # exact dimensions
![[audio.mp3]]                   # embed audio player
![[video.mp4]]                   # embed video player
![[document.pdf]]                # embed PDF
![[document.pdf#page=3]]         # embed specific page
```

Supported formats — see `references/file-formats.md`.

### Callouts

```markdown
> [!note] Optional Title
> Content with **Markdown** and [[wikilinks]].

> [!tip]- Foldable (collapsed by default)
> Hidden content.

> [!warning]+ Foldable (expanded by default)
> Shown content.
```

13 types: `note`, `abstract`/`summary`/`tldr`, `info`, `todo`, `tip`/`hint`/`important`, `success`/`check`/`done`, `question`/`help`/`faq`, `warning`/`caution`/`attention`, `failure`/`fail`/`missing`, `danger`/`error`, `bug`, `example`, `quote`/`cite`.

### Other Obsidian Extensions

```markdown
==highlighted text==             # highlight
%%hidden comment%%               # not rendered
- [ ] incomplete task            # task
- [x] completed task             # done task
$E = mc^2$                       # inline LaTeX
$$\int_0^\infty f(x)dx$$         # block LaTeX
This is a footnote[^1].         # footnote
[^1]: Footnote content.
```

### Tags

```markdown
#tag                             # simple tag
#parent/child                    # nested tag
```

Tags in body text or frontmatter. No spaces allowed.

### Mermaid Diagrams

````markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```
````

## Canvas — JSON Canvas Spec 1.0

Full spec: `references/canvas-spec.md`

### Quick Reference

```json
{
  "nodes": [
    {
      "id": "node1",
      "type": "text",
      "x": 0, "y": 0,
      "width": 400, "height": 200,
      "text": "# Title\n\nMarkdown content",
      "color": "4"
    },
    {
      "id": "node2",
      "type": "file",
      "x": 500, "y": 0,
      "width": 400, "height": 400,
      "file": "path/to/note.md",
      "subpath": "#heading"
    },
    {
      "id": "node3",
      "type": "link",
      "x": 0, "y": 300,
      "width": 400, "height": 300,
      "url": "https://example.com"
    },
    {
      "id": "group1",
      "type": "group",
      "x": -50, "y": -50,
      "width": 1000, "height": 500,
      "label": "Group Name",
      "color": "5"
    }
  ],
  "edges": [
    {
      "id": "edge1",
      "fromNode": "node1",
      "fromSide": "right",
      "toNode": "node2",
      "toSide": "left",
      "color": "1",
      "label": "relates to"
    }
  ]
}
```

Node types: `text`, `file`, `link`, `group`.
Colors: `"1"` red, `"2"` orange, `"3"` yellow, `"4"` green, `"5"` cyan, `"6"` purple, or hex `"#FF0000"`.
Edge endpoints: `fromEnd`/`toEnd` → `"none"` or `"arrow"` (toEnd defaults to `"arrow"`).
Sides: `top`, `right`, `bottom`, `left`.

### Canvas Layout Tips

- Use a grid: nodes at multiples of 50px
- Standard node: 400×200 (text), 400×400 (file/link)
- Groups: 50px padding around contained nodes
- Nodes array order = z-index (last = top)

## File Naming

```
kebab-case.md                    # note files
YYYY-MM-DD-title.md             # daily/dated notes
kebab-case.canvas               # canvas files
```

No spaces, no special chars, no CJK in filenames (for Git cross-platform safety).

## Vault Structure

```
vault/
├── 00-inbox/                    # new/unsorted notes
├── 01-projects/                 # active projects
├── 02-areas/                    # ongoing areas
├── 03-resources/                # reference material
├── 04-archive/                  # archived notes
├── assets/                      # images, PDFs, attachments
├── canvas/                      # .canvas files
├── templates/                   # note templates
└── .gitignore
```

## .gitignore

```gitignore
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/app.json
.trash/
.DS_Store
.smart-connections/
```

Keep `.obsidian/` tracked (minus volatile files) so plugins/themes sync.

## Guardrails

- Never modify `.obsidian/` config files
- Always use `[[wikilinks]]` not `[text](file.md)` for internal links
- UTF-8 encoding, LF line endings
- Attachment paths relative to vault root
- Test canvas JSON validity before writing