{"id":41541849,"url":"https://github.com/llbbl/semantic-docs","last_synced_at":"2026-03-11T23:09:59.938Z","repository":{"id":318792453,"uuid":"1076415885","full_name":"llbbl/semantic-docs","owner":"llbbl","description":"Documentation theme with semantic vector search","archived":false,"fork":false,"pushed_at":"2026-02-24T03:11:13.000Z","size":326,"stargazers_count":13,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T09:38:05.150Z","etag":null,"topics":["astrojs","react","tailwindcss","theme","themes","typescript"],"latest_commit_sha":null,"homepage":"https://vault.llbbl.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/llbbl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T20:35:59.000Z","updated_at":"2026-02-24T03:11:16.000Z","dependencies_parsed_at":"2025-10-15T21:00:27.346Z","dependency_job_id":"e13a1f6c-e5a7-4ccd-8197-fddb75da6063","html_url":"https://github.com/llbbl/semantic-docs","commit_stats":null,"previous_names":["llbbl/semantic-docs"],"tags_count":9,"template":true,"template_full_name":null,"purl":"pkg:github/llbbl/semantic-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llbbl%2Fsemantic-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llbbl%2Fsemantic-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llbbl%2Fsemantic-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llbbl%2Fsemantic-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/llbbl","download_url":"https://codeload.github.com/llbbl/semantic-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llbbl%2Fsemantic-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30406417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T22:36:59.286Z","status":"ssl_error","status_checked_at":"2026-03-11T22:36:57.544Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrojs","react","tailwindcss","theme","themes","typescript"],"created_at":"2026-01-24T01:17:44.646Z","updated_at":"2026-03-11T23:09:59.933Z","avatar_url":"https://github.com/llbbl.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# semantic-docs\n\n[![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)\n\nDocumentation theme with semantic vector search.\n\nA 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.\n\n## Features\n\n- 🎨 **Modern Dark UI** - Sleek design with OKLCH colors\n- 🔍 **Semantic Search** - AI-powered vector search in the header\n- 📱 **Responsive** - Mobile-friendly with collapsible sidebar\n- 📑 **Auto TOC** - Table of contents generated from headings\n- 🚀 **Edge-Ready** - Optimized for Turso's global database\n- ⚡ **Fast** - Static generation with server-rendered search\n- 🎯 **Type-Safe** - Full TypeScript support\n\n## Quick Start\n\n### 1. Clone or Use as Template\n\n```bash\ngit clone https://github.com/llbbl/semantic-docs.git\ncd semantic-docs\n```\n\nOr use as a template on GitHub.\n\n### 2. Install Dependencies\n\n```bash\npnpm install\n```\n\nOptional: use the `justfile` task runner for common commands:\n\n```bash\njust\njust dev\njust test\n```\n\nSee `docs/just.md` for the full list of recipes.\n\n### 3. Set Up Environment\n\nCopy `.env.example` to `.env` and add your credentials:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env`:\n\n```env\nTURSO_DB_URL=libsql://your-database.turso.io\nTURSO_AUTH_TOKEN=your-auth-token\n```\n\n**Get Turso credentials:**\n\n```bash\n# Install Turso CLI\ncurl -sSfL https://get.tur.so/install.sh | bash\n\n# Sign up and authenticate\nturso auth signup\n\n# Create a database\nturso db create my-docs\n\n# Get credentials\nturso db show my-docs\n```\n\n### 4. Add Your Content\n\nCreate markdown files in `./content`:\n\n```bash\nmkdir -p content/getting-started\necho \"# Hello World\\n\\nThis is my first article.\" \u003e content/getting-started/intro.md\n```\n\n**Front matter support:**\n\n```markdown\n---\ntitle: Getting Started\ntags: [tutorial, beginner]\n---\n\n# Getting Started\n\nYour content here...\n```\n\n### 5. Index Content\n\n```bash\n# Initialize database and index content to Turso\npnpm db:init\npnpm index\n\n# Or use local database without Turso (for testing)\npnpm db:init:local\npnpm index:local\n```\n\nThis will:\n- Scan your markdown files\n- Generate embeddings (using local model by default)\n- Store everything in Turso (or local.db with `:local` commands)\n\n### 6. Start Development\n\n```bash\npnpm dev\n```\n\nVisit `http://localhost:4321` to see your docs!\n\n## Customization\n\n### Change Site Title\n\nEdit `src/components/DocsHeader.astro`:\n\n```astro\n\u003cspan class=\"font-sans\"\u003eYour Site Name\u003c/span\u003e\n```\n\nAnd `src/layouts/DocsLayout.astro`:\n\n```astro\nconst { title = \"Your Site Name\", description = \"Your description\" } = Astro.props;\n```\n\n### Customize Colors\n\nEdit `src/styles/global.css` to change the color scheme. The theme uses OKLCH colors for smooth gradients and perceptual uniformity.\n\n### Embeddings\n\nSemantic search uses local embeddings by default, so no API keys are required.\n\n## Project Structure\n\n```\nsemantic-docs/\n├── src/\n│   ├── components/\n│   │   ├── DocsHeader.astro    # Header with search\n│   │   ├── DocsSidebar.astro   # Navigation sidebar\n│   │   ├── DocsToc.tsx         # Table of contents\n│   │   └── Search.tsx          # Search component\n│   ├── layouts/\n│   │   └── DocsLayout.astro    # Main layout\n│   ├── lib/\n│   │   └── turso.ts            # Database client\n│   ├── pages/\n│   │   ├── api/\n│   │   │   └── search.json.ts  # Search API endpoint\n│   │   ├── content/\n│   │   │   └── [...slug].astro # Article pages\n│   │   └── index.astro         # Home page\n│   └── styles/\n│       └── global.css          # Global styles\n├── scripts/\n│   └── index-content.js        # Indexing script\n├── content/                    # Your markdown files\n├── astro.config.mjs\n├── package.json\n└── .env                        # Your credentials\n```\n\n## Deployment\n\n### Container-Based Platforms (Recommended)\n\nThis project is designed to run on platforms that support Docker containers, such as:\n\n- [Railway](https://railway.app)\n- [Render](https://render.com)\n- [Fly.io](https://fly.io)\n- Google Cloud Run\n- AWS ECS/Fargate\n- Azure Container Apps\n- Coolify\n\n```bash\n# Build with Node.js adapter (default)\npnpm build\n\n# The built application runs on Node.js and can be containerized\n# Set environment variables in your platform's dashboard\n```\n\n**Important:** Always run `pnpm index` before deploying to ensure content is indexed.\n\n### Vercel / Netlify\n\n\u003e **Note**: These platforms have not been tested and cannot be recommended at this time.\n\n```bash\n# Build with Node.js adapter (default)\npnpm build\n\n# Deploy\nvercel\n# or\nnetlify deploy --prod\n\n# Add environment variables in platform dashboard\n```\n\n## Content Organization\n\nThe theme automatically organizes content by folder:\n\n```\ncontent/\n├── getting-started/\n│   ├── intro.md\n│   └── installation.md\n├── guides/\n│   ├── configuration.md\n│   └── deployment.md\n└── reference/\n    └── api.md\n```\n\nFolders become collapsible sections in the sidebar.\n\n## Search\n\nThe search bar in the header provides semantic search:\n\n- **Semantic matching**: Finds content by meaning, not just keywords\n- **Instant results**: Real-time as you type\n- **Smart ranking**: Most relevant results first\n- **Tag display**: Shows article tags in results\n\nTry searching for concepts rather than exact phrases!\n\n## Build for Production\n\n```bash\n# Index content\npnpm index\n\n# Build site\npnpm build\n\n# Preview\npnpm preview\n```\n\n## Troubleshooting\n\n### Search not working\n\n1. Check `.env` file has correct credentials\n2. Ensure `output: 'server'` in `astro.config.mjs`\n3. Verify content is indexed: run `pnpm index`\n\n### Content not showing\n\n1. Run `pnpm index` to index your markdown files\n2. Check content is in `./content` directory\n3. Verify Turso database has data\n\n### Local embedding model slow\n\nFirst run downloads ~50MB model. Subsequent runs use cache.\n\n## Tech Stack\n\n- **Framework**: [Astro](https://astro.build) 5\n- **Search**: [libsql-search](https://github.com/llbbl/libsql-search)\n- **Database**: [Turso](https://turso.tech) (libSQL)\n- **Styling**: [Tailwind CSS](https://tailwindcss.com) 4\n- **UI**: React islands for interactivity\n- **Embeddings**: Xenova (local)\n\n## License\n\nMIT\n\n## Support\n\n- [Issues](https://github.com/llbbl/semantic-docs/issues)\n- [Discussions](https://github.com/llbbl/semantic-docs/discussions)\n\n## Credits\n\nBuilt with [libsql-search](https://github.com/llbbl/libsql-search).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllbbl%2Fsemantic-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllbbl%2Fsemantic-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllbbl%2Fsemantic-docs/lists"}