Riebeckite
Menu
Color mode

Publishing Obsidian notes

This guide shows how to use Markdown notes from an Obsidian vault as the content for a Riebeckite site.

The basic idea

Riebeckite turns Markdown files from a configured folder into a site. An Obsidian vault is also a Markdown folder, so you can point content.directory at the vault.

You do not have to rebuild an existing vault for Riebeckite. Riebeckite reads Markdown from the configured folder; it does not rewrite your notes as part of normal dev, check, doctor, inspect, or build commands. Keep using Obsidian as your editor, and opt in only the notes you want to publish.

Each note decides whether it is published through frontmatter.

md
---
title: Published note
publish: true
---

Notes without publish: true are not published by the default explicit publish strategy. This lets you keep private notes and public articles in the same vault.

Pattern A: Put the vault inside the site

This is the simplest setup. Open the generated site's content/ folder as an Obsidian vault.

text
my-site/
|- content/        <- open this folder in Obsidian
|- riebeckite.config.ts
`- package.json

The default configuration works for this pattern.

ts
content: {
  directory: "content",
},

Use this pattern first if you only want to try Riebeckite.

Pattern B: Keep the vault and site in separate folders

If you already have an Obsidian vault, place the site next to it.

text
workspace/
|- notes/      <- existing Obsidian vault
`- my-site/    <- Riebeckite site

In my-site/riebeckite.config.ts, point content.directory at the vault.

ts
content: {
  directory: "../notes",
},

../notes means "the notes folder one level above the site". For more advanced separation, see Separating content from the site.

This pattern is safe for an existing vault as long as you understand the publish rule: only notes with publish: true become public by default. Riebeckite reads the vault during preview and build; it does not reorganize the vault or edit Markdown files for you.

Writing notes in Obsidian

For a note you want to publish, add at least these frontmatter fields.

md
---
title: Article title
publish: true
---

Write the body as normal Markdown.

md
# Heading
 
Write the article body here.
 
You can link to [[another note]].

The file name becomes part of the URL. For example, content/my-note.md becomes /my-note. Non-English file names can work, but short lowercase English names are easier to share as URLs.

Images and attachments

Keep images and attachments inside the vault.

md
![Photo](/images/photo.jpg)

If you use an Obsidian attachments folder, keep that folder inside the vault. Files outside the vault may not be found during the build.

Riebeckite resolves [[links]] against note paths, aliases, and attachment names. When two notes, two aliases, or two attachments share the same name, a bare name cannot identify one target. Riebeckite never guesses: the link stays unresolved and doctor reports it as ambiguous.

text
x/dup.md
y/dup.md
md
[[dup]]     <- ambiguous
[[x/dup]]   <- explicit, resolves to x/dup.md

Add the folder to the link, or rename one of the files, so every published link points at exactly one target.

Keeping private notes private

Do not add publish: true to private notes.

md
---
title: Private note
---

The private note itself will not be published. Avoid linking from public articles to private notes, and run doctor before publishing.

sh
npm exec riebeckite doctor

Check before publishing

sh
npm exec riebeckite check
npm exec riebeckite doctor
npm exec riebeckite build

check validates configuration, doctor inspects content and links, and build writes the publishable files.

Next steps

History

1 changesCollapseExpand
1 + # Publishing Obsidian notes
2 +
3 + This guide shows how to use Markdown notes from an Obsidian vault as the content for a Riebeckite site.
4 +
5 + ## The basic idea
6 +
7 + Riebeckite turns Markdown files from a configured folder into a site. An Obsidian vault is also a Markdown folder, so you can point `content.directory` at the vault.
8 +
9 + You do not have to rebuild an existing vault for Riebeckite. Riebeckite reads Markdown from the configured folder; it does not rewrite your notes as part of normal `dev`, `check`, `doctor`, `inspect`, or `build` commands. Keep using Obsidian as your editor, and opt in only the notes you want to publish.
10 +
11 + Each note decides whether it is published through frontmatter.
12 +
13 + ```md
14 + ---
15 + title: Published note
16 + publish: true
17 + ---
18 + ```
19 +
20 + Notes without `publish: true` are not published by the default explicit publish strategy. This lets you keep private notes and public articles in the same vault.
21 +
22 + ## Pattern A: Put the vault inside the site
23 +
24 + This is the simplest setup. Open the generated site's `content/` folder as an Obsidian vault.
25 +
26 + ```text
27 + my-site/
28 + |- content/ <- open this folder in Obsidian
29 + |- riebeckite.config.ts
30 + `- package.json
31 + ```
32 +
33 + The default configuration works for this pattern.
34 +
35 + ```ts
36 + content: {
37 + directory: "content",
38 + },
39 + ```
40 +
41 + Use this pattern first if you only want to try Riebeckite.
42 +
43 + ## Pattern B: Keep the vault and site in separate folders
44 +
45 + If you already have an Obsidian vault, place the site next to it.
46 +
47 + ```text
48 + workspace/
49 + |- notes/ <- existing Obsidian vault
50 + `- my-site/ <- Riebeckite site
51 + ```
52 +
53 + In `my-site/riebeckite.config.ts`, point `content.directory` at the vault.
54 +
55 + ```ts
56 + content: {
57 + directory: "../notes",
58 + },
59 + ```
60 +
61 + `../notes` means "the `notes` folder one level above the site". For more advanced separation, see [Separating content from the site](./content-repositories.en.md).
62 +
63 + This pattern is safe for an existing vault as long as you understand the publish rule: only notes with `publish: true` become public by default. Riebeckite reads the vault during preview and build; it does not reorganize the vault or edit Markdown files for you.
64 +
65 + ## Writing notes in Obsidian
66 +
67 + For a note you want to publish, add at least these frontmatter fields.
68 +
69 + ```md
70 + ---
71 + title: Article title
72 + publish: true
73 + ---
74 + ```
75 +
76 + Write the body as normal Markdown.
77 +
78 + ```md
79 + # Heading
80 +
81 + Write the article body here.
82 +
83 + You can link to [[another note]].
84 + ```
85 +
86 + The file name becomes part of the URL. For example, `content/my-note.md` becomes `/my-note`. Non-English file names can work, but short lowercase English names are easier to share as URLs.
87 +
88 + ## Images and attachments
89 +
90 + Keep images and attachments inside the vault.
91 +
92 + ```md
93 + ![Photo](/images/photo.jpg)
94 + ```
95 +
96 + If you use an Obsidian attachments folder, keep that folder inside the vault. Files outside the vault may not be found during the build.
97 +
98 + ## Duplicate names and ambiguous links
99 +
100 + Riebeckite resolves `[[links]]` against note paths, aliases, and attachment names. When two notes, two aliases, or two attachments share the same name, a bare name cannot identify one target. Riebeckite never guesses: the link stays unresolved and `doctor` reports it as ambiguous.
101 +
102 + ```text
103 + x/dup.md
104 + y/dup.md
105 + ```
106 +
107 + ```md
108 + [[dup]] <- ambiguous
109 + [[x/dup]] <- explicit, resolves to x/dup.md
110 + ```
111 +
112 + Add the folder to the link, or rename one of the files, so every published link points at exactly one target.
113 +
114 + ## Keeping private notes private
115 +
116 + Do not add `publish: true` to private notes.
117 +
118 + ```md
119 + ---
120 + title: Private note
121 + ---
122 + ```
123 +
124 + The private note itself will not be published. Avoid linking from public articles to private notes, and run `doctor` before publishing.
125 +
126 + ```sh
127 + npm exec riebeckite doctor
128 + ```
129 +
130 + ## Check before publishing
131 +
132 + ```sh
133 + npm exec riebeckite check
134 + npm exec riebeckite doctor
135 + npm exec riebeckite build
136 + ```
137 +
138 + `check` validates configuration, `doctor` inspects content and links, and `build` writes the publishable files.
139 +
140 + ## Next steps
141 +
142 + - [Writing content](./writing-content.en.md)
143 + - [Separating content from the site](./content-repositories.en.md)
144 + - [Content System](../framework/content-system.en.md)
145 +