Obsidian

Table of contents

A Markdown-superset tailored for Obsidian.

Install

The plugin

Install Raindown from Obsidian's community plugins: in Settings → Community plugins, select Browse, search for Raindown, select Install, then Enable.

The program

The plugin needs the raindown program, which it can't install for you. Paste one of these commands into a terminal and press Return. It takes about a minute, and running it again updates Raindown. Then select Check again, or run Raindown: Find Raindown from the command palette.

Open Terminal by pressing Cmd + Space and typing Terminal, then run:

Open a terminal by pressing Ctrl + Alt + T, or by searching your apps for Terminal, then run:

Open PowerShell by pressing the Windows key and typing PowerShell, then run:

curl -fsSL https://raindown.dev/install.sh | sh
curl -fsSL https://raindown.dev/install.sh | sh
irm https://raindown.dev/install.ps1 | iex

Both check the download against the release's checksums. You can read them first, at install.sh and install.ps1, or download a binary yourself, or install the gem.

Features

Metadata

Underscored values in file paths are automatically converted to metadata. For example, in the following file path...

docs/_basics/_1-getting-started.md

...the _basics and _1 produce metadata that is equivalent to the following front matter:

---
folder: basics
order: 1
---

Tip

Separate multiple folder tags with &:
docs/_1&_basics/_1-getting-started.md

List

list: writes a link to each note with a tag or in a folder, like list: tags: 'book'

list: tags: 'book'
- [Dune](books/Dune.md)
- [Hyperion](books/Hyperion.md)

Table

table: writes a CSV or TSV file in your vault into the note as a table. Edit a cell in the note and it's written back to the file, and changing the file updates the table.

Obsidian doesn't open CSV files, so a table has an Open CSV button beside it, which opens its file in your spreadsheet app. The file's made the first time the note's written back, from the table you've typed below it, or else with a table to fill in.

The quickest way to change a table is in the note, which always writes back to its file. In a spreadsheet app, save the file as CSV for the note to update: Excel saves it in place, but Numbers keeps your changes in a separate .numbers file unless you choose File → Export To → CSV and replace the original.

table: 'data/books.csv'
<!-- table 2 rows · f690ac -->
| title    | rating |
| -------- | ------ |
| Dune     | 5      |
| Hyperion | 4      |

Charts

chart: draws a CSV, TSV, JSON or YAML file in your vault.

chart: 'data/reading.csv'
```
Jan  ███████████████████████▊                 320
Feb  ████████████████████████████████████████ 540
Mar  ██████████████████████████████▍          410
```

Table of contents

toc: writes an inline TOC which updates as you add and rename headings.

# Books

toc:
- [Reading](#reading)
- [Finished](#finished)

## Reading

## Finished

Components

A note in your vault's .raindown folder, like BookCard.md, is a component with no code, a template whose properties fill its {variables}, like BookCard: title: Dune rating: 5.

Settings

Setting Default Description
Raindown command raindown The raindown executable, or its full path
Write-back On Write back to a note with directives as you type
Bare syntax Off Recognise bare directives on their own line like toc: (equivalent to CLI --bare)

A bare directive, on its own line like toc:, only writes back in a note with raindown: true in its front matter, unless Bare syntax is on. Only names Raindown knows like toc:, list: and your project's nodes write anything, so a line like Summary: is left alone.

Warning

Make sure your files are version controlled or backed up before enabling bare syntax, otherwise existing content beneath text like list: could be overwritten.

Adding, renaming or removing a note writes back the notes with lists, like list:, so they don't go stale.

Commands

Command Does
Raindown: Write back this note Writes back now, and says what happened
Raindown: Run the endpoints in this note Runs the endpoints without a response, like -x
Raindown: Write back all notes Writes back every note with directives, and says how many changed
Raindown: Find Raindown Looks for Raindown again, once you've installed it
Raindown: Open this table's file Opens the file of the table at the cursor, in your spreadsheet app

Note

Unlike the CLI endpoints in Obsidian never run on save, only via the command.

Requirements

The raindown executable, which you install yourself. The plugin never installs or updates it, as Obsidian's developer policies don't allow that.

The first time the plugin can't find it, it looks in ~/.local/bin, or %LOCALAPPDATA%\Programs\raindown on Windows, and on your shell's PATH, which Obsidian opened from the Dock doesn't have. If it's not there either, it shows the command to run, and Check again or Raindown: Find Raindown looks again once you have. You can also set the plugin's Raindown command to its full path.

It's desktop only, as Obsidian on phones can't run Raindown.

Files and network