Installation

This page takes you from an empty machine to a running site. It assumes nothing about Riebeckite, and it never asks you to clone the Riebeckite repository.

Requirements

npm ships with Node.js, so you do not install it separately.

Confirm Node.js is available:

node -v
npm -v

Both should print a version such as v22.0.0. If a command is not found, install Node.js and reopen the terminal.

Create a site

In the folder where you want the site, run the generator:

npx create-riebeckite

npx downloads create-riebeckite and runs it once; nothing is installed globally. The CLI asks, in order:

1. Project name — the folder to create, for example my-site
2. Preset — the site's composition; keep starter when unsure. See Presets
3. Content source — This project keeps content/ inside the site and is the simplest start. Separate GitHub repository is an advanced setup for an existing vault: it asks for the content and site repositories and configures GitHub Actions deployment automatically. See Content Repositories
4. Deployment — Cloudflare Workers, GitHub Actions, or Not now. Cloudflare Workers installs dependencies and then asks Deploy now?, so you can publish your first version right away. GitHub Actions deploys on every push. Not now skips deployment setup; see Deployment

To script the same setup instead of answering prompts, pass arguments, for example:

npx create-riebeckite my-site --preset starter

• If the target folder already has files, the command stops instead of overwriting. Add --force only when you really want to overwrite.
• List the available presets with npx create-riebeckite --list-presets.

Then move into the folder and install the packages:

cd my-site
npm install

The @riebeckite/* packages are published to npm, so this is all it takes. The first install can take a minute.

What gets generated

The exact files depend on the preset: empty generates a bare application shell, starter generates a practical site with connected sample notes, and showcase adds references, rendered examples, and local fixtures. See Presets.

Directory structure

The generated site folder looks like this:

my-site/
├─ content/               Your Markdown files
├─ public/                Static files
├─ app/                   Generated app code (rarely edited)
├─ riebeckite.config.ts   Site configuration
├─ package.json
├─ vite.config.ts
├─ tsconfig.json
├─ README.md
└─ dist/                  Production build output (after build)

Point the settings at your site

Open riebeckite.config.ts and edit the site block:

site: {
  title: "My Blog",
  description: "Notes from my days",
  baseUrl: "https://example.com",
  locale: "en",
},

The rest of the generated config (content, theme, plugins) already matches the preset. Full field documentation is in Configuration.

Start the development server

npm exec riebeckite dev

The terminal prints a URL such as http://localhost:5173. Open it in a browser; Markdown and application edits are picked up while the server runs. Press Ctrl + C to stop.

Everyday commands

Run these from inside the site folder:

npm exec riebeckite dev           # start the development server
npm exec riebeckite build         # write the publishable files to dist/
npm exec -- riebeckite build --full  # rebuild without incremental reuse

For the first successful run, dev and build are enough. If something looks wrong later, the CLI also has read-only diagnostic commands such as check, doctor, and inspect; see the CLI reference.

Next

• First Content →