semantic-docs — Astro Documentation Template

SHA-256: 8167c3215330ce395e300a0f678608734246212ea042a4ae20c8fe077b94b220

2026-10-05T03:29:45.213Z

# semantic-docs

[![Coverage](https://img.shields.io/codecov/c/github/llbbl/semantic-docs?label=coverage)](https://codecov.io/gh/llbbl/semantic-docs) [![CI](https://github.com/llbbl/semantic-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/llbbl/semantic-docs/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/llbbl/semantic-docs)](https://github.com/llbbl/semantic-docs/releases)

`semantic-docs` is an Astro documentation theme with built-in semantic search powered by [`@logan/libsql-search`](https://github.com/llbbl/libsql-search). It gives you static docs pages, a server-rendered search API, and a libSQL/Turso-backed content index without adding a separate hosted search product.

Use it when you want:

- semantic search over Markdown content with a small operational footprint
- a docs site you can ship quickly without giving up control of layout, content, or deployment
- a lightweight alternative to bolting on a hosted search product

## What You Get

- Semantic search in the header, backed by libSQL/Turso
- Static article pages with a server-rendered search endpoint
- Sidebar navigation and table of contents generated from your content
- A local development path that works without Turso credentials

## Quick Start

Requires Node.js `>=22.13.0` and pnpm `11`.

```bash
git clone https://github.com/llbbl/semantic-docs.git
cd semantic-docs
pnpm install
pnpm db:init:local
pnpm index:local
pnpm dev
```

Open `http://localhost:4321`.

The local path works without Turso credentials, but indexing and search both
call Cloudflare Workers AI, so `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`
must be set before `pnpm index:local`. Copy `.env.example` to `.env` to fill them
in. The current repo defaults to the `articles_cf_bgem3_1024` index at 1024
dimensions, the fixed width of `@cf/baai/bge-m3`. When you want a remote
libSQL/Turso database, switch to the `.env`-driven commands in the docs.

Text you index and every search query are sent to Cloudflare.

### Without credentials

To run the whole pipeline with no accounts at all, start the bundled offline
embedding service in a second terminal and point the app at it:

```bash
pnpm embeddings:offline
OFFLINE_EMBEDDINGS_BASE_URL=http://127.0.0.1:8788/v1 pnpm db:init:local
OFFLINE_EMBEDDINGS_BASE_URL=http://127.0.0.1:8788/v1 pnpm index:local
OFFLINE_EMBEDDINGS_BASE_URL=http://127.0.0.1:8788/v1 pnpm dev
```

This is what CI uses, so fork and Dependabot pull requests exercise indexing,
prerendering, and search. Its vectors are a hashed bag of words rather than a
model, and live in their own table — good enough to prove the pipeline runs, and
not a basis for judging search quality.

## Documentation

- [Docs index](./docs/README.md)
- [Setup and indexing](./docs/GETTING_STARTED.md)
- [Deployment notes](./docs/DEPLOYMENT.md)
- [Project reference](./docs/REFERENCE.md)
- [Security considerations](./docs/SECURITY.md)
- [Just task runner](./docs/just.md)

## Content Shape

Store Markdown under `./content` using folder-based sections:

```text
content/
├── getting-started/
│   └── intro.md
├── guides/
│   └── deployment.md
└── reference/
    └── api.md
```

Folders become sidebar groups, and frontmatter can define `title`, `tags`,
`description`, and `order`. Folder order is configured in `src/config/nav.ts`.

## Development Checks

```bash
pnpm format
pnpm lint
pnpm exec tsc --noEmit
pnpm test
```

## License

MIT