Skip to content
Readsmith

Quickstart

By the end of this page you have a documentation site running locally and know where your own content goes.

Prerequisites

  • Docker with the Compose plugin, for the standard path
  • or Node.js 22+ and pnpm, for a local preview without containers

Run the site

  1. Clone the repository

    git clone https://github.com/readsmith/readsmith
cd readsmith

  2. Create your environment file

    cp .env.example .env

    Open .env and set POSTGRES_PASSWORD. Everything else has a working default.

  3. Start the stack

    docker compose up

    Two services start: the app and Postgres with pgvector. There is nothing else to run.

  4. Open the site

    Visit http://localhost:4321. You are looking at the bundled sample content, served exactly the way your docs will be.

Point it at your docs

Set READSMITH_CONTENT to the directory that holds your content, then restart. The directory can be as small as this:

my-docs/
├── index.md
└── guides/
    └── setup.md

No configuration file is required: pages are discovered, titles come from your headings, and the navigation builds itself from the folder structure. When you want control, add a docs.yaml:

site:
  name: My Project
  description: What my project does.

Every key it accepts is in the settings reference.

Write your first page

Create index.md in your content directory:

# My Project

Welcome. This page is served precompiled, with zero JavaScript.

Rebuild (or let the dev server pick it up) and the page is live, present in navigation, listed in llms.txt, and indexed for search.

Was this page helpful?