ReallySimpleDocs
A simple documentation system for Astro, built with Basecoat and Tailwind CSS.
ReallySimpleDocs keeps docs portable: content lives in docs/, navigation lives in docs/docs.json, and the Astro integration owns the docs UI, search, Markdown exports, and LLM files.

Install
Requires Astro 7.4.13 or newer within version 7, Node.js 22.23.4 or newer, Basecoat 1.2.1 or newer within version 1, and Tailwind CSS 4.3 or newer within version 4. Version 1.1 drops Astro 6 support.
Add ReallySimpleDocs to an Astro site:
npm install reallysimpledocs basecoat-css tailwindcss
Configure the integration:
// astro.config.mjs
import { defineConfig } from "astro/config";
import reallySimpleDocs from "reallysimpledocs/astro";
export default defineConfig({
integrations: [
reallySimpleDocs({
docsDir: "./docs",
routeBase: "/docs",
style: "nova",
site: {
title: "Acme Docs",
description: "Documentation for Acme.",
url: "https://docs.example.com",
favicon: "favicon.svg",
socialImage: "social.png",
},
}),
],
});
Create your first docs page:
docs/
├── docs.json
└── index.md
{
"menu": [
{
"type": "group",
"label": "Docs",
"items": [{ "slug": "index", "icon": "info" }]
}
]
}
# Introduction
Welcome to the docs.
What it provides
- Static docs routes from Markdown and MDX files.
- Sidebar navigation from docs/docs.json.
- Lunr search with a built-in command dialog.
- Syntax-highlighted code blocks with copy buttons.
- llms.txt, llms-full.txt, and per-page Markdown exports.
- Basecoat styling with style-specific RSD CSS for docs surfaces.
- Component slots for additive head content, sidebar chrome, and header controls.
Customization
Use components.ContentHeader for controls between search and the built-in theme toggle:
reallySimpleDocs({
components: {
ContentHeader: "./src/components/ContentHeader.astro",
},
});
Use components.Head to add tags to <head>. RSD's built-in metadata, theme setup, Basecoat JavaScript (including code copying), and search behavior still render.
Use customCss for project CSS imported after Basecoat and RSD styles:
reallySimpleDocs({
style: "nova",
customCss: ["./src/docs.css"],
});
Use css: false only when you provide the full Tailwind/Basecoat/RSD stylesheet pipeline yourself. RSD exports its own CSS for that case:
@import "reallysimpledocs/css";
Search outside docs
Render the exported CommandDialog on any Astro page where you want docs search:
---
import { CommandDialog } from "reallysimpledocs/components";
---
<CommandDialog />
<button type="button" class="btn" onclick="window.rsdOpenCommandSearch?.()">
Search docs
</button>
Local development
npm install
npm run dev
Run the checks before opening a pull request:
npm run check
It builds the site, checks the built output (scripts/assert-site-output.mjs), then packs the package and builds a throwaway consumer app from the tarball (npm run smoke:consumer). CI runs the same command on every pull request and push to main. Use npm pack --dry-run to see which files would be published.
Documentation
Go to reallysimpledocs.com.
Support
- Report issues
- Star the project on GitHub
License
Releases
See CHANGELOG.md for release notes and upgrade requirements.
See the release workflow in CONTRIBUTING.md for staged npm publishing and docs deployment.