Separating Content and the Site (In Depth)

Separating Content from the Site explains separate-repository operation as a walkthrough. This page is its "in depth" companion: it explains why the configuration works this way and covers the cases you dig into later — root resolution, copying assets, authenticating CI, and running submodules.

If you are new, read separating content from the site first, and use this page when you want to understand the mechanics or when operations go wrong.

1. Why "outside the site" works

The resolution rules for content.directory in riebeckite.config.ts:

The key point: a relative content.directory is always relative to appRoot, and does not change when configRoot or the working directory changes. The integration resolves all three roots before running content or plugins, and the CLI uses the same result. So from a nested directory, a CI working directory, or an editor task, the same vault is always read.

// site/riebeckite.config.ts
export default defineConfig({
  content: {
    directory: "../vault", // relative to appRoot
  },
});

Do not assemble the value from process.cwd(), and do not point appRoot at the vault. The vault is source data; the Vite application root stays the site.

1-1. How the roots are determined

Walking through the order reveals the common pitfalls.

1. The CLI walks up from the working directory looking for riebeckite.config.ts / .js / .mjs. The directory of the first match becomes configRoot. If none is found it fails with Could not find riebeckite.config.*.
2. appRoot is found by scanning under configRoot for vite.config.ts / .js / .mjs (skipping node_modules, .git, and tests). Finding none is an error, and finding more than one is also an error.
3. contentRoot resolves as path.resolve(appRoot, content.directory). An absolute directory lands on the same value here.

If you intentionally keep riebeckite.config.ts outside the Vite application, pass configRoot and appRoot to riebeckiteVite(). Either way, the base for a relative content.directory stays appRoot.

In other words, "the same vault from anywhere" holds as long as the config is inside (or above) the site and appRoot is unambiguous. Running from an unrelated directory finds no config at all, and a monorepo with multiple vite.config.* files fails with Found multiple Vite applications. Both mean the tool could not pin down which site's config applies.

1-2. Reading content from the application side

The integration exposes the resolved config and a ready ContentManager as framework-owned modules, so application code imports them rather than re-reading riebeckite.config.ts:

import { config } from "virtual:riebeckite/config";
import { content } from "virtual:riebeckite/content";

config.content.directory is already absolute, so resolving it again against another base is a common source of errors. A script that runs outside Vite can resolve the same values with resolveHonoxConfig from @riebeckite/honox/runtime.

1-3. What not to do

• Build content.directory from process.cwd(). The result changes with where you run.
• Point appRoot (Vite's root) at the vault. That moves the site's app/, public/, and build output.
• Assume a relative directory is relative to configRoot. The base is always appRoot.

2. The three patterns

2-1. Pattern A layout

blog/
├─ riebeckite.config.ts     ← appRoot (directory: "content")
├─ app/
├─ public/
└─ content/                 ← articles live here
   └─ index.md

The simplest option, and exactly what create-riebeckite generates. Article visibility matches the repository.

2-2. Pattern B layout

notes-repo/
├─ site/                ← appRoot (contains riebeckite.config.ts)
│  └─ riebeckite.config.ts
└─ vault/               ← referenced by directory: "../vault"

One repository and one history, with the locations split. Visibility is still per repository, as in A. The only change from A is content.directory: "../vault".

2-3. Sharing one vault across several sites

An extension of C: keep the vault in its own place and have several sites reference it.

workspace/
├─ notes/           ← shared vault (its own private repository)
├─ blog/            ← site 1 (directory: "../notes")
└─ docs/            ← site 2 (directory: "../notes")

Treat the vault as read-only source data and vary exclude, publishStrategy, and plugins per site. No site writes back, so the same notes can be published in different shapes. Deploy each site independently, giving each CI the additional checkout from section 3-2.

2-4. Decision flow

1. You want articles private, or updates decoupled → C.
2. Articles and site can share visibility → next.
3. You only want locations and settings apart → B. You want one repository → A.
4. You want one vault for several sites → C + shared vault (2-3).

3. Pattern C in detail

The basic flow is in separating content from the site. This section adds the details that walkthrough omits.

3-1. Keep the vault in a private repository

• After git init, create the private GitHub repository before the first push.
• .obsidian/ is generated when Obsidian opens the vault. Even if it is pushed, putting .obsidian/** in content.exclude keeps it out of the site build. If you do not want to track it, a middle ground is to gitignore only .obsidian/workspace*.json.
• The baseline for private notes is: no publish: true. Add a second layer by excluding a private folder (for example private/**) in content.exclude so those notes are not even loaded.
• Leave publishStrategy at the default explicit. selective is the "publish almost everything, hide exceptions" model, which is riskier for a private vault.

3-2. Fetching content is separate from triggering a deployment

The default deploy workflow (generated by --github-actions) checks out only the site repository.

Option 1: extra checkout plus repository dispatch (recommended for automatic deployment)

- name: Check out the site
  uses: actions/checkout@v4
 
- name: Check out the notes
  uses: actions/checkout@v4
  with:
    repository: <you>/notes
    token: ${{ secrets.RIEBECKITE_CONTENT_READ_TOKEN || github.token }}
    path: content

• With path: content, set content.directory to "content".
• This checkout makes files available only after the site workflow starts. Add repository_dispatch: types: [content-updated] to the site workflow and put a notification workflow in the content repository to start it on its main pushes.
• Do not set ref when article updates should deploy the newest default-branch content. The checkout then reads its current tip; the default fetch-depth: 1 is enough.

Option 2: Git submodule

cd my-site
git submodule add git@github.com:<you>/notes.git content

• content becomes a link to the articles repository; align directory in riebeckite.config.ts with content.
• Add submodules: recursive to actions/checkout@v4 in the workflow so CI fetches the dependency.
• The referenced commit of a submodule is recorded in the site repository. Updating articles is a two-step operation: update the reference on the site side, commit, and push.

cd content && git pull
cd ..
git add content
git commit -m "update articles"

git submodule update --remote follows the latest remote, but you still need the site-side commit.

Comparing the options

If article updates dominate, Option 1 is the easier fit; if you want the history pinned on the site side, use Option 2.

3-3. Authentication for private repositories in CI

• github.token is scoped to the current repository. It can read another public GitHub repository, but cannot read a different private or internal repository.
• For a private/internal vault, register RIEBECKITE_CONTENT_READ_TOKEN in the site repository. Use a fine-grained PAT restricted to the vault with Contents: read, or an equivalent read-only GitHub App installation token.
• The content notification needs a separate SITE_DISPATCH_TOKEN stored only in the content repository. Restrict a fine-grained PAT to the site repository with Contents: read and write; classic PATs require repo scope and GitHub App tokens require Contents: write.
• If the submodule was added with an SSH URL (git@github.com:...), CI needs an SSH key. Switching to an HTTPS URL and passing token: is simpler to configure.

- name: Check out the notes
  uses: actions/checkout@v4
  with:
    repository: <you>/notes
    token: ${{ secrets.NOTES_READ_TOKEN }}
    path: notes

3-4. Keep the local and CI layouts aligned

A relative directory is appRoot-relative, so different layouts locally and in CI resolve differently.

Changing the value (../notes locally, notes in CI) points both at the same vault. If you would rather use one value, either keep the vault under my-site locally or make CI lay it out as ../notes.

4. Publication rules and assets

4-1. How publication is decided

content.filters.publishStrategy takes two values.

The decision is centralized in isPublished / isPublishable, and note rendering, diagnostics, and the prebuild asset collection all use the same rule. Do not reimplement the publication decision on the site side; that is how "visible in preview, missing in production" disagreements start.

4-2. How to write exclude

exclude matches glob patterns against the path relative to contentRoot (normalized to / separators). Note that patterns are anchored to the whole path.

* stays within one segment; ** crosses segments. If a folder of the same name can appear in subfolders, prefix **/ to be safe. That is why the scaffold defaults use **/templates/** and **/private/**.

exclude filters before loading, so excluded notes never appear in link resolution or the graph. For notes you want private, in addition to leaving off publish: true, exclude the whole folder where possible.

4-3. Content images and attachments are published differently

Vault files fall into three kinds, and each one is published by a different owner:

Content images need nothing from the site side: obsidianMarkdown() writes every image referenced from a published page into the build output, keeping its logical path, and the development server serves the same logical path straight from the content. Images that nothing references, or that only non-public pages reference, are not written.

Attachments and media are different. An embed such as:

![[attachments/report.pdf]]

produces a URL, but the file itself is not copied into the public directory. Add a prebuild step on the site side that copies only the files you publish. Reference implementation: apps/web/scripts/build_images.ts (called from the prebuild script, tsx scripts/build_images.ts, copying into public/assets/attachments/).

That implementation works like this:

1. Walk contentRoot to enumerate images (IMAGE_EXTENSIONS) and attachments (isAttachmentPath).
2. Build the content with ContentManager and collect only the assets referenced by published notes — from links and from src / href in the rendered HTML.
3. Copy only referenced assets into public/assets/attachments/<relative path from the vault> (images into public/<relative path>, so the dev server can serve them before the first build), skipping the copy when size and mtime are unchanged.
4. Delete orphaned attachments that exist in public but not in content.

In short, the rule is "copy because a published note references it", not "copy because it exists in the vault". Do not take the shortcut of copying the entire vault. It risks leaking private notes, images referenced only from non-public pages, unreferenced attachments, and .obsidian metadata. Content images are already filtered and emitted by the build; attachment and media publishing stays the site application's responsibility, so copy only the files a published note references. To detect a published note that crosses the boundary by linking to an unpublished one, run riebeckite-diagnostics from @riebeckite/plugin-diagnostics; it reports those references as publish-boundary warnings, and runDiagnostics() produces the same result programmatically. See Diagnostics.

4-4. The generated URL

A content image keeps its logical path from the vault:

Vault:
assets/logo.png
 
Public URL:
/assets/logo.png

Attachments and media use a dedicated prefix so that a file and an image with the same name cannot collide:

/assets/attachments/<relative logical path from the vault>

• attachment() reads the embedded file's size from the resolved vault root and rejects paths outside the root.
• media() renders the matching audio/video for the same logical path.

Keeping the physical location under public/ consistent with the visible URL reduces post-build 404s.

5. Verification

You can confirm roots and publication boundaries before building, with the CLI. Run it from a nested directory to prove the working directory does not matter.

cd site/app
npm exec riebeckite check
npm exec riebeckite doctor
npm exec riebeckite inspect config
npm exec -- riebeckite inspect content --list
npm exec riebeckite inspect graph
npm exec riebeckite build

Check the results in this order:

1. check validates the configuration and plugin contracts.
2. doctor reports unreadable or invalid filesystem content sources.
3. In inspect config, Directory is the resolved absolute path, Publishing is publishStrategy, and Exclude is the pattern count. Settle where the vault points here first.
4. Before investigating WikiLinks or embeds, use inspect content --list to confirm the expected logical paths are loaded.
5. Use inspect graph to confirm notes you excluded are not appearing as nodes.
6. build validates the integration and route rendering.

6. Troubleshooting (in depth)

Further reading

• Separating Content from the Site — a step-by-step introduction
• Configuration — root resolution and external vaults in detail
• Usage Guide — external vault examples and assets
• Cloudflare deploy template — deployment workflow details