semantic-docs

semantic-docs is an Astro documentation theme with built-in semantic search powered by @logan/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.

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:

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
• Setup and indexing
• Deployment notes
• Project reference
• Security considerations
• Just task runner

Content Shape

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

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

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

License

MIT