Basics

Who this guide is for

• You write notes in Obsidian and want them managed separately from the site code
• You want articles private and only the site public
• You want one vault shared by several sites
• You want article updates and site updates deployed independently

If all you want is a small personal blog in a single repository, there is no need to split anything. Pattern A (one repository) is enough.

Start with one repository

The beginner setup keeps content and site code together:

site repository
├─ content/
├─ app/
├─ riebeckite.config.ts
└─ package.json

This is what npx create-riebeckite my-site generates. Use it for your first site unless you already know you need a separate vault or repository.

flowchart LR
    Repo["Site repository"]
 
    Repo --> App["app/"]
    Repo --> Content["content/"]
    Repo --> Config["riebeckite.config.ts"]

When the split is useful, the shape becomes:

site repository           content repository
├─ app/                  ├─ article-a.md
├─ riebeckite.config.ts  ├─ article-b.md
└─ ...                   └─ attachments/

The site repository owns the app, configuration, theme, plugins, and deployment. The content repository owns Markdown and attachments.

flowchart LR
    Content["Content repository<br/>Markdown / Vault"]
    Site["Site repository<br/>Code / Config / Theme"]
    Build["Riebeckite build"]
    Public["Public site"]
 
    Content --> Build
    Site --> Build
    Build --> Public

Riebeckite build combines both to produce the final site.

The idea: articles can live outside the site

content.directory in riebeckite.config.ts is a relative path from the site root (appRoot) and can point at a folder outside it. Articles do not have to live inside the site.

// site/riebeckite.config.ts
export default defineConfig({
  content: {
    directory: "../vault", // the vault folder one level above the site
  },
  // ...
});

The base for a relative path is always the site root. So the same vault is read whether you run the CLI from app/ inside the site or from a CI working directory. If you replace the standard filesystem reader with a custom content.source, content.directory is not used. The precise definitions (appRoot / configRoot / contentRoot) are in Configuration, "Filesystem root and an external vault".

With this, you can split things like:

Choose a pattern

First decide at what granularity to split articles from the site.

How to decide:

• You do not want articles public → C. With a private repository, a forgotten publish: true cannot expose the content itself.
• Articles and site are both fine to publish → A or B. One repository to manage.
• You want article updates decoupled from the site deploy → C. Add a repository-dispatch notification if an articles push must start a deploy; an extra checkout alone only supplies files to a deploy that already started.
• You want one vault shared by several sites → C, or a layout where the vault lives independently. Keep the vault in one place and have each site reference it read-only.

flowchart TD
    Start{"Do you need to separate repositories?"}
 
    Start -->|"Not really"| A["A. One repository"]
    Start -->|"Just separate folders"| B["B. Separate folders, one repository"]
    Start -->|"Keep articles private"| C["C. Separate repositories"]
    Start -->|"Decouple updates"| C
    Start -->|"Share a vault across sites"| C

The steps below are for C. For A and B the configuration is the same; only step 5 (fetching the articles repository in deployment) is unnecessary.