semantic-docs

Documentation theme with semantic vector search.

A beautiful, dark-mode documentation theme powered by libsql-search for semantic search capabilities. Perfect for technical documentation, knowledge bases, and content-heavy sites.

Features

• 🎨 Modern Dark UI - Sleek design with OKLCH colors
• 🔍 Semantic Search - AI-powered vector search in the header
• 📱 Responsive - Mobile-friendly with collapsible sidebar
• 📑 Auto TOC - Table of contents generated from headings
• 🚀 Edge-Ready - Optimized for Turso's global database
• ⚡ Fast - Static generation with server-rendered search
• 🎯 Type-Safe - Full TypeScript support

Quick Start

1. Clone or Use as Template

git clone https://github.com/llbbl/semantic-docs.git
cd semantic-docs

Or use as a template on GitHub.

2. Install Dependencies

pnpm install

Optional: use the justfile task runner for common commands:

just
just dev
just test

See docs/just.md for the full list of recipes.

3. Set Up Environment

Copy .env.example to .env and add your credentials:

cp .env.example .env

Edit .env:

TURSO_DB_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

Get Turso credentials:

# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# Sign up and authenticate
turso auth signup

# Create a database
turso db create my-docs

# Get credentials
turso db show my-docs

4. Add Your Content

Create markdown files in ./content:

mkdir -p content/getting-started
echo "# Hello World\n\nThis is my first article." > content/getting-started/intro.md

Front matter support:

---
title: Getting Started
tags: [tutorial, beginner]
---

# Getting Started

Your content here...

5. Index Content

# Initialize database and index content to Turso
pnpm db:init
pnpm index

# Or use local database without Turso (for testing)
pnpm db:init:local
pnpm index:local

This will:

• Scan your markdown files
• Generate embeddings (using local model by default)
• Store everything in Turso (or local.db with :local commands)

6. Start Development

pnpm dev

Visit http://localhost:4321 to see your docs!

Customization

Change Site Title

Edit src/components/DocsHeader.astro:

<span class="font-sans">Your Site Name</span>

And src/layouts/DocsLayout.astro:

const { title = "Your Site Name", description = "Your description" } = Astro.props;

Customize Colors

Edit src/styles/global.css to change the color scheme. The theme uses OKLCH colors for smooth gradients and perceptual uniformity.

Embeddings

Semantic search uses local embeddings by default, so no API keys are required.

Project Structure

semantic-docs/
├── src/
│   ├── components/
│   │   ├── DocsHeader.astro    # Header with search
│   │   ├── DocsSidebar.astro   # Navigation sidebar
│   │   ├── DocsToc.tsx         # Table of contents
│   │   └── Search.tsx          # Search component
│   ├── layouts/
│   │   └── DocsLayout.astro    # Main layout
│   ├── lib/
│   │   └── turso.ts            # Database client
│   ├── pages/
│   │   ├── api/
│   │   │   └── search.json.ts  # Search API endpoint
│   │   ├── content/
│   │   │   └── [...slug].astro # Article pages
│   │   └── index.astro         # Home page
│   └── styles/
│       └── global.css          # Global styles
├── scripts/
│   └── index-content.js        # Indexing script
├── content/                    # Your markdown files
├── astro.config.mjs
├── package.json
└── .env                        # Your credentials

Deployment

Container-Based Platforms (Recommended)

This project is designed to run on platforms that support Docker containers, such as:

• Railway
• Render
• Fly.io
• Google Cloud Run
• AWS ECS/Fargate
• Azure Container Apps
• Coolify

# Build with Node.js adapter (default)
pnpm build

# The built application runs on Node.js and can be containerized
# Set environment variables in your platform's dashboard

Important: Always run pnpm index before deploying to ensure content is indexed.

Vercel / Netlify

Note: These platforms have not been tested and cannot be recommended at this time.

# Build with Node.js adapter (default)
pnpm build

# Deploy
vercel
# or
netlify deploy --prod

# Add environment variables in platform dashboard

Content Organization

The theme automatically organizes content by folder:

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

Folders become collapsible sections in the sidebar.

Search

The search bar in the header provides semantic search:

• Semantic matching: Finds content by meaning, not just keywords
• Instant results: Real-time as you type
• Smart ranking: Most relevant results first
• Tag display: Shows article tags in results

Try searching for concepts rather than exact phrases!

Build for Production

# Index content
pnpm index

# Build site
pnpm build

# Preview
pnpm preview

Troubleshooting

Search not working

1. Check .env file has correct credentials
2. Ensure output: 'server' in astro.config.mjs
3. Verify content is indexed: run pnpm index

Content not showing

1. Run pnpm index to index your markdown files
2. Check content is in ./content directory
3. Verify Turso database has data

Local embedding model slow

First run downloads ~50MB model. Subsequent runs use cache.

Tech Stack

• Framework: Astro 5
• Search: libsql-search
• Database: Turso (libSQL)
• Styling: Tailwind CSS 4
• UI: React islands for interactivity
• Embeddings: Xenova (local)

License

MIT

Support

• Issues
• Discussions

Credits

Built with libsql-search.