Silica is a framework for publishing Obsidian-flavored markdown vaults as polished, authenticated, server-rendered knowledge sites.

Read the documentation at silicajs.dev.

The user's project stays small:

content/
public/
silica.config.ts
package.json

silica dev and silica build run precompute, materialize the Next.js scaffold under .silica/next/, and treat that output as a disposable build artifact.

npm install
npm run build
npm run --workspace docs build

To create a new vault after packages are published:

npx create-silica my-vault
cd my-vault
npm install
npm run dev

1. @silicajs/cli materializes .silica/next/ from templates in @silicajs/next.
2. @silicajs/core scans content/, filters drafts, builds .silica/next/data/vault.db, writes runtime markdown to .silica/next/data/content, and copies assets to .silica/next/public/silica/.
3. Next.js (via @silicajs/next) renders vault pages from .silica/next/app/[[...slug]]/page.tsx. The cached VaultContent server component queries vault.db, reads markdown from disk, and returns a React tree.
4. The theme owns persistent layout chrome while @silicajs/components provides the vault tree, breadcrumbs, ToC, backlinks, dark mode, and search UI on top of @silicajs/ui primitives.
5. Auth settings are baked into generated proxy.ts, which enforces access before cached pages, search, or vault assets are served.

Silica prerenders all notes by default. Every rendered note is cacheable, so a page that is not prerendered is rendered on first request and reused afterward. Large vaults can reduce build work by configuring render.prerender:

export default defineConfig({
  render: {
    prerender: { depth: 2 },
  },
});

Supported modes are prerender: "all", prerender: "none", depth-based prerendering, and custom selectors with include, exclude, and limit.

render.output selects the deployment output: the default ("default") emits a regular Next.js build so the hosting platform's adapter (for example, Vercel) bundles the server and manages caching, while "standalone" emits a self-contained server for self-hosting (for example, Docker) and automatically enables Silica's filesystem cache handler (configurable via render.cache.directory).

npm install
npm run build
npm test
npm run typecheck

The docs site and dogfood fixture lives in docs/.

silica build emits a standalone Next.js production app in .silica/next/.next/. The scaffolded Dockerfile copies:

• .silica/next/.next/standalone/
• .silica/next/.next/static/
• .silica/next/public/
• .silica/next/data/

This keeps runtime content rendering available while serving through a minimal Node image.

Projects scaffolded with silica create include a Dockerfile:

docker build -t my-silica-site .
docker run --env-file .env -p 3000:3000 -v silica-cache:/app/data/cache/next my-silica-site

The generated image starts the traced Next.js standalone server.js. If auth is enabled, the generated proxy also protects search and vault assets under /silica/*. Mounting /app/data/cache/next preserves rendered-note cache entries across container replacement for single-container deployments. Multi-replica deployments need a genuinely shared volume or a future Redis/S3/KV cache handler.

npm ci
npm run build
npm run start

silica start runs the standalone output when present, falling back to next start for development-like environments.

Use the scaffolded Dockerfile as the deployment target. Configure the same environment variables as .env.example (BETTER_AUTH_SECRET, BETTER_AUTH_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) in the platform dashboard. Auth requires a strong BETTER_AUTH_SECRET in production and at least one allowedDomains or allowedEmails entry in silica.config.ts. For Fly.io, expose internal port 3000; for Railway, the container listens on $PORT/3000.