obsidian-markdown

name: obsidian-markdown description: Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes.

Obsidian Flavored Markdown Skill

This skill enables skills-compatible agents to create and edit valid Obsidian Flavored Markdown, including all Obsidian-specific syntax extensions.

Overview

Obsidian uses a combination of Markdown flavors:

• CommonMark
• GitHub Flavored Markdown
• LaTeX for math
• Obsidian-specific extensions (wikilinks, callouts, embeds, etc.)

Scratchpad in this deployment

This deployment does not grant the agent broad filesystem access to an external Obsidian vault.

All agent-authored notes must live under the repo-root scratchpad:

• <SCRATCHPAD_ROOT>/ where <SCRATCHPAD_ROOT> = <REPO_ROOT>/scratchpad

User-scoped content must be stored under:

• users/[USER_ID]/ (per-user area; default write target)

Selection rules:

• If the user does not specify, default to users/[USER_ID]/.
• Always scope reads/writes to the current user’s folder users/[USER_ID]/ so information between users will not be mixed.
  • Never read/write another user’s folder (e.g. users/<someone-else>/) unless the user explicitly requests it and you can confirm it’s the same tenant/user.
  • If [USER_ID] is not known from the current context, ask for it before creating/modifying any files under users/.
• Do not modify content outside users/[USER_ID]/ unless the user explicitly asks.

Path conventions:

• When you propose creating/editing a note, include a concrete filesystem path like: <SCRATCHPAD_ROOT>/users/[USER_ID]/<relative-path>.md

Safe file discovery (when the exact note path is unknown)

If the user asks for a note but does not provide an exact filename/path (e.g. “what’s on my shopping list?”), and the vault is accessible at runtime, you should:

1. Search within the expected folder(s) (usually users/[USER_ID]/).
2. Keep searches bounded (limit depth, limit results) and ask a clarifying question if multiple candidates match.
3. Read the most likely candidates (using file_read) until you find the requested content.

Recommended bounded search patterns (use shell tool):

• Find likely shopping list notes (names only):

  • find <SCRATCHPAD_ROOT>/users/[USER_ID] -maxdepth 4 -type f \( -iname '*shop*' -o -iname '*grocery*' -o -iname '*list*' \) -print | head -n 20

• Content search (bounded; prefer ripgrep if available):

  • rg -n --max-count 20 -S "shopping|grocery" <SCRATCHPAD_ROOT>/users/[USER_ID] 2>/dev/null || true

Then, for the top candidates:

• file_read(path="/full/path/to/note.md", mode="view")

If you cannot find a unique match:

• Ask the user to confirm the note name or folder, or to share one line from the note header.

Personality files

Personality/identity instructions are stored as markdown files under the scratchpad:

• Per-user:
  • users/[USER_ID]/soul.md
  • users/[USER_ID]/id.md

Default fallback templates live in the repo:

• instructions/soul.md
• instructions/id.md

When the per-user file is missing, the backend will fall back to the repo defaults under instructions/.

• For obsidian://open links:
  • vault should be the vault name on that device (it’s the folder name you opened in Obsidian).
  • file should be a path within the scratchpad/vault, e.g. users/[USER_ID]/Notes/Welcome.md.

Basic Formatting

Paragraphs and Line Breaks

This is a paragraph.

This is another paragraph (blank line between creates separate paragraphs).

For a line break within a paragraph, add two spaces at the end  
or use Shift+Enter.

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Text Formatting

Escaping Formatting

Use backslash to escape special characters:

\*This won't be italic\*
\#This won't be a heading
1\. This won't be a list item

Common characters to escape: \*, \_, \#, \`, \|, \~

Internal Links (Wikilinks)

Basic Links

[[Note Name]]
[[Note Name.md]]
[[Note Name|Display Text]]

Link to Headings

[[Note Name#Heading]]
[[Note Name#Heading|Custom Text]]
[[#Heading in same note]]
[[##Search all headings in vault]]

Link to Blocks

[[Note Name#^block-id]]
[[Note Name#^block-id|Custom Text]]

Define a block ID by adding ^block-id at the end of a paragraph:

This is a paragraph that can be linked to. ^my-block-id

For lists and quotes, add the block ID on a separate line:

> This is a quote
> With multiple lines

^quote-id

Search Links

[[##heading]]     Search for headings containing "heading"
[[^^block]]       Search for blocks containing "block"

Markdown-Style Links

[Display Text](Note%20Name.md)
[Display Text](Note%20Name.md#Heading)
[Display Text](https://example.com)
[Note](obsidian://open?vault=VaultName&file=Note.md)

Note: Spaces must be URL-encoded as %20 in Markdown links.

Embeds

Embed Notes

![[Note Name]]
![[Note Name#Heading]]
![[Note Name#^block-id]]

Embed Images

![[image.png]]
![[image.png|640x480]]    Width x Height
![[image.png|300]]        Width only (maintains aspect ratio)

External Images

![Alt text](https://example.com/image.png)
![Alt text|300](https://example.com/image.png)

Embed Audio

![[audio.mp3]]
![[audio.ogg]]

Embed PDF

![[document.pdf]]
![[document.pdf#page=3]]
![[document.pdf#height=400]]

Embed Lists

![[Note#^list-id]]

Where the list has been defined with a block ID:

- Item 1
- Item 2
- Item 3

^list-id

Embed Search Results

```query
tag:#project status:done
```

Callouts

Basic Callout

> [!note]
> This is a note callout.

> [!info] Custom Title
> This callout has a custom title.

> [!tip] Title Only

Foldable Callouts

> [!faq]- Collapsed by default
> This content is hidden until expanded.

> [!faq]+ Expanded by default
> This content is visible but can be collapsed.

Nested Callouts

> [!question] Outer callout
> > [!note] Inner callout
> > Nested content

Supported Callout Types

Custom Callouts (CSS)

.callout[data-callout="custom-type"] {
  --callout-color: 255, 0, 0;
  --callout-icon: lucide-alert-circle;
}

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item
  - Another nested
- Item 3

* Also works with asterisks
+ Or plus signs

Ordered Lists

1. First item
2. Second item
   1. Nested numbered
   2. Another nested
3. Third item

1) Alternative syntax
2) With parentheses

Task Lists

- [ ] Incomplete task
- [x] Completed task
- [ ] Task with sub-tasks
  - [ ] Subtask 1
  - [x] Subtask 2

Quotes

> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.
>
> > Nested quotes work too.

Code

Inline Code

Use `backticks` for inline code.
Use double backticks for ``code with a ` backtick inside``.

Code Blocks

```
Plain code block
```

```javascript
// Syntax highlighted code block
function hello() {
  console.log("Hello, world!");
}
```

```python
# Python example
def greet(name):
    print(f"Hello, {name}!")
```

Nesting Code Blocks

Use more backticks or tildes for the outer block:

````markdown
Here's how to create a code block:
```js
console.log("Hello")
```
````

Tables

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Alignment

| Left | Center | Right |
| :--- | :----: | ----: |
| Left | Center | Right |

Using Pipes in Tables

Escape pipes with backslash:

| Column 1          | Column 2        |
| ----------------- | --------------- |
| [[Link\|Display]] | ![[Image\|100]] |

Math (LaTeX)

Inline Math

This is inline math: $e^{i\pi} + 1 = 0$

Block Math

$$
\begin{vmatrix}
a & b \\
c & d
\end{vmatrix} = ad - bc
$$

Common Math Syntax

$x^2$              Superscript
$x_i$              Subscript
$\frac{a}{b}$      Fraction
$\sqrt{x}$         Square root
$\sum_{i=1}^{n}$   Summation
$\int_a^b$         Integral
$\alpha, \beta$    Greek letters

Diagrams (Mermaid)

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do this]
    B -->|No| D[Do that]
    C --> E[End]
    D --> E
```

Sequence Diagrams

```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob
    Bob-->>Alice: Hi Alice
```

Linking in Diagrams

```mermaid
graph TD
    A[Biology]
    B[Chemistry]
    A --> B
    class A,B internal-link;
```

Footnotes

This sentence has a footnote[^1].

[^1]: This is the footnote content.

You can also use named footnotes[^note].

[^note]: Named footnotes still appear as numbers.

Inline footnotes are also supported.^[This is an inline footnote.]

Comments

This is visible %%but this is hidden%% text.

%%
This entire block is hidden.
It won't appear in reading view.
%%

Horizontal Rules

---
***
___
- - -
* * *

Properties (Frontmatter)

Properties use YAML frontmatter at the start of a note:

---
title: My Note Title
date: 2024-01-15
tags:
  - project
  - important
aliases:
  - My Note
  - Alternative Name
cssclasses:
  - custom-class
status: in-progress
rating: 4.5
completed: false
due: 2024-02-01T14:30:00
---

Property Types

Default Properties

• tags - Note tags
• aliases - Alternative names for the note
• cssclasses - CSS classes applied to the note

Tags

#tag
#nested/tag
#tag-with-dashes
#tag_with_underscores

In frontmatter:
---
tags:
  - tag1
  - nested/tag2
---

Tags can contain:

• Letters (any language)
• Numbers (not as first character)
• Underscores _
• Hyphens -
• Forward slashes / (for nesting)

HTML Content

Obsidian supports HTML within Markdown:

<div class="custom-container">
  <span style="color: red;">Colored text</span>
</div>

<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

Complete Example

---
title: Project Alpha
date: 2024-01-15
tags:
  - project
  - active
status: in-progress
priority: high
---

# Project Alpha

## Overview

This project aims to [[improve workflow]] using modern techniques.

> [!important] Key Deadline
> The first milestone is due on ==January 30th==.

## Tasks

- [x] Initial planning
- [x] Resource allocation
- [ ] Development phase
  - [ ] Backend implementation
  - [ ] Frontend design
- [ ] Testing
- [ ] Deployment

## Technical Notes

The main algorithm uses the formula $O(n \log n)$ for sorting.

```python
def process_data(items):
    return sorted(items, key=lambda x: x.priority)
```

## Architecture

```mermaid
graph LR
    A[Input] --> B[Process]
    B --> C[Output]
    B --> D[Cache]
```

## Related Documents

- ![[Meeting Notes 2024-01-10#Decisions]]
- [[Budget Allocation|Budget]]
- [[Team Members]]

## References

For more details, see the official documentation[^1].

[^1]: https://example.com/docs

%%
Internal notes:
- Review with team on Friday
- Consider alternative approaches
%%

References

• Basic formatting syntax
• Advanced formatting syntax
• Obsidian Flavored Markdown
• Internal links
• Embed files
• Callouts
• Properties