https://github.com/llbbl/semantic-docs
Documentation theme with semantic vector search
https://github.com/llbbl/semantic-docs
astrojs react tailwindcss theme themes typescript
Last synced: 4 months ago
JSON representation
Documentation theme with semantic vector search
- Host: GitHub
- URL: https://github.com/llbbl/semantic-docs
- Owner: llbbl
- License: mit
- Created: 2025-10-14T20:35:59.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-02-24T03:11:13.000Z (4 months ago)
- Last Synced: 2026-02-24T09:38:05.150Z (4 months ago)
- Topics: astrojs, react, tailwindcss, theme, themes, typescript
- Language: TypeScript
- Homepage: https://vault.llbbl.com/
- Size: 318 KB
- Stars: 13
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
# semantic-docs
[](https://codecov.io/gh/llbbl/semantic-docs) [](https://github.com/llbbl/semantic-docs/actions/workflows/ci.yml) [](https://github.com/llbbl/semantic-docs/releases)
Documentation theme with semantic vector search.
A beautiful, dark-mode documentation theme powered by [libsql-search](https://github.com/llbbl/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
```bash
git clone https://github.com/llbbl/semantic-docs.git
cd semantic-docs
```
Or use as a template on GitHub.
### 2. Install Dependencies
```bash
pnpm install
```
Optional: use the `justfile` task runner for common commands:
```bash
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:
```bash
cp .env.example .env
```
Edit `.env`:
```env
TURSO_DB_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token
```
**Get Turso credentials:**
```bash
# 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`:
```bash
mkdir -p content/getting-started
echo "# Hello World\n\nThis is my first article." > content/getting-started/intro.md
```
**Front matter support:**
```markdown
---
title: Getting Started
tags: [tutorial, beginner]
---
# Getting Started
Your content here...
```
### 5. Index Content
```bash
# 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
```bash
pnpm dev
```
Visit `http://localhost:4321` to see your docs!
## Customization
### Change Site Title
Edit `src/components/DocsHeader.astro`:
```astro
Your Site Name
```
And `src/layouts/DocsLayout.astro`:
```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](https://railway.app)
- [Render](https://render.com)
- [Fly.io](https://fly.io)
- Google Cloud Run
- AWS ECS/Fargate
- Azure Container Apps
- Coolify
```bash
# 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.
```bash
# 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
```bash
# 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](https://astro.build) 5
- **Search**: [libsql-search](https://github.com/llbbl/libsql-search)
- **Database**: [Turso](https://turso.tech) (libSQL)
- **Styling**: [Tailwind CSS](https://tailwindcss.com) 4
- **UI**: React islands for interactivity
- **Embeddings**: Xenova (local)
## License
MIT
## Support
- [Issues](https://github.com/llbbl/semantic-docs/issues)
- [Discussions](https://github.com/llbbl/semantic-docs/discussions)
## Credits
Built with [libsql-search](https://github.com/llbbl/libsql-search).