Obsidian Notes

Obsidian Notes

(since 5.1) --dialect=obsidian (PdfOptions::dialect = MarkdownDialect::Obsidian; in the desktop app, Markdown: Obsidian in the options) reads a note as Obsidian shows it. The default, --dialect=github, reads none of this, as GitHub shows all of it as text.

rayomd --export note.md note.pdf --dialect=obsidian
rayomd --book vault-folder vault.pdf --dialect=obsidian --toc

Obsidian syntax	In the PDF
> [!tip] Title	A callout: a coloured bar and the title in bold in that colour. All of Obsidian's types and aliases: note, info, todo (blue); abstract, summary, tldr, tip, hint, important (cyan); success, check, done (green); question, help, faq, warning, caution, attention (orange); failure, fail, missing, danger, error, bug (red); example (purple); quote, cite (grey). A type Obsidian does not know is a note.
> [!faq] without a title	The type's name as the title: "Faq".
> [!tip]- and > [!tip]+	Folded or not: both are printed unfolded.
> [!quote] Title alone	A callout of only its title.
> > [!bug] inside a callout	Nested callouts, each in its own colour.
==text==	Highlighted, as <mark>.
%%comment%%, also over lines	Left out.
[[Note]], [[Note|text]]	A link to Note.md showing "Note" or "text".
[[Note#Heading]]	A link to the heading in Note.md, showing "Note > Heading".
[[#Heading]]	A link to the heading in this note.
[[#^block]]	Its text: block references have no target in a PDF.
![[image.png]]	The image (PNG, JPEG, SVG).
![[image.png|300]], ![[image.png|300x200]]	The image 300 pixels wide (and 200 high) when the embed has a line of its own; elsewhere at its size.
![[image.png|a cat]]	The image with "a cat" as its alt text.
![[Note]] on a line of its own	(since 5.2) The note itself, printed in its place (see below); in 5.1 and with --embeds=link, a link to it. Elsewhere in a line, a link.
![[Note#Heading]], ![[Note#^id]]	(since 5.2) That heading's section, or the paragraph or list item that block id marks.
text ^id at a line's end, ^id alone	(since 5.2) Left out.
#tag	Printed as text; (since 5.2) left out with --hide-tags.

In a table, [[Note\|text]] works as in Obsidian (the \| does not split the cell).

Links between notes

In a single PDF a wiki link to another note is a link to its file (Note.md), as a Markdown link [Note](Note.md) would be. In a book (--book with a folder, files or a SUMMARY.md), a wiki link goes to the note's first page in the PDF, or to the heading it names: the note is found where the link says, and otherwise by its name anywhere in the book, in any case ([[Setup]] finds guides/setup.md), as Obsidian finds notes in a vault.

Embedded notes (since 5.2)

A note embedded on a line of its own, ![[Note]], is printed where it stands, as Obsidian's own PDF export does: the whole note without its front matter, ![[Note#Heading]] that heading's section, ![[Note#^id]] the paragraph or list item the block id marks. Embedded notes may embed others, up to 8 levels deep. Their footnotes come with them (numbered with the note's own, never mixed up with them), their images are found from their own folder, and their headings join the table of contents and the heading numbers.

rayomd --export report.md report.pdf --dialect=obsidian --vault="$HOME/Notes"

• Where notes are found. Next to the embedding note, then from the vault's top, then by name anywhere in the vault (skipping hidden folders such as .obsidian and .trash), as Obsidian finds them. A name with a dot ([[v1.2 notes]]) finds v1.2 notes.md.
• The vault. --vault=DIR (PdfOptions::vaultRoot); by default the note's own folder. Nothing outside it is read, through .. or symbolic links either; with a vault, the note's local images may lie anywhere in it.
• What stays a link. A cycle, a missing note, the 1,001st embed of a document, embedded text past 32 MiB, embeds in lists, quotes and callouts, every embed with --embeds=link (PdfOptions::embedsAsLinks), and every embed of a note read from stdin (it has no folder). Markdown links (not wiki links) in an embedded note go from the main note's folder.
• Cost. About 18 µs per embedded note per export on Linux (one openat2 a candidate).

Linked notes and backlinks (since 5.2)

--follow-links[=N] (with --export) makes a book of the note and the notes it links to, N links deep (1 to 6, default 1), breadth first and each once: wiki links under the dialect, relative .md links in either dialect, found as embedded notes are, in the vault. At most 1,000 notes; past that a warning on stderr says how many were left out (exit code 0). Each linked note starts a new page, titled with its file name when it does not begin with a heading.

--backlinks (PdfOptions::backlinks, any book: --book too) ends each file with "Linked from:" and links to the files of the book that link to it.

rayomd --export project.md project.pdf --dialect=obsidian --follow-links=2 --backlinks --toc

Tags (since 5.2)

--hide-tags (PdfOptions::hideTags) leaves Obsidian's #tags out: a # at a line's start or after a blank, then letters, digits, _, - or /, with at least one character that is not a digit (#1984 is no tag, #y1984 is). Tags in code, formulas, comments and wiki links stay; each tag goes with one space next to it, and a line of tags alone becomes a blank line.

Where the syntax is left as written

Fenced code blocks, code spans, formulas ($…$, $$…$$), the YAML front matter and the table of contents marker [[_TOC_]] are left alone. Inside indented code (four spaces) the syntax is still read: put such examples in fenced code.

How it works

The syntax is turned into Markdown and HTML that RayoMD reads before the note is parsed, in one pass and line for line (so the desktop app's editor and preview stay together); callouts are read by the parser itself. Wiki links therefore follow the same URL rules as other links, and embedded images the same local-image rules as other images. Text with thousands of unclosed [[, == or %% stays linear in time. Details: src/core/dialect.cpp and AGENTS.md.