Newshot

Show HN: ReallySimpleDocs – Modern, AI-ready documentation site with Astro

Original text(via HN AI)

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.

ReallySimpleDocs screenshot
ReallySimpleDocs screenshot

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.

The text above was extracted automatically from the source page and may miss images, tables or code blocks. The original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗