Knowledge Core

Modern monorepo template for documentation and course platforms — with a built-in AI assistant

A production-ready template based on Astro v6, MDX, Tailwind CSS v4, and pnpm Workspaces - optimized for creating technical documentation and interactive learning platforms. Ships with a RAG-based AI chat assistant powered by Cloudflare Vectorize and Workers AI that answers questions about your content in real time.

Live Previews

Docs App:kc-docs.casoon.dev
Courses App:kc-courses.casoon.dev
Chat Worker:https://knowledge-core-chat-worker.casoon.workers.dev/chat

The AI assistant is live on both apps — click the chat button in the bottom-right corner and ask anything about the documentation or courses.

Tech Stack

Technology	Version	Purpose
Astro	6.3	Framework — Vite Environment API, Content Collections, ClientRouter
MDX	5.0	Markdown with interactive components
Tailwind CSS	4.3	CSS-first config, Vite plugin, design tokens
Biome	2.4	Linting, formatting, a11y, security & complexity checks
Zod	4.x	Runtime validation for content schemas
TypeScript	6.0	Strict mode throughout
pnpm	9.x	Workspaces with catalog for centralized dependency management
Node.js	>= 22.12	Runtime
Cloudflare Vectorize	v2	Vector database for semantic content search
Cloudflare Workers AI	—	Embedding model (`bge-large-en-v1.5`) + LLM (`llama-3-8b-instruct`)
Cloudflare Workers	—	Edge-deployed chat backend

Features

AI Chat Assistant — RAG-based chat widget backed by Cloudflare Vectorize + Workers AI; answers questions about your docs and courses in real time
Shared Components — Reusable UI components across apps
Interactive Courses — Quiz, exercises, progress tracking
Dark Mode — With theme persistence via ClientRouter
Cloud Sync — Sync learning progress across devices
Pre-Commit Hooks — Husky + lint-staged with Biome auto-fix
Post-Build Audit — SEO & a11y checks via @casoon/astro-post-audit
Configurable Sidebar — defineSidebar() with autogenerate, groups, manual links, and badges
Extended Frontmatter — draft, editUrl, pagefind, sidebar.badge, prev/next (Starlight-inspired)
Pagefind-Optimized — NavBar/Footer excluded from index; per-page pagefind: false support
Unit Tests — Vitest for content schemas (docs, courses, sidebar) and i18n utils
Link Validation — pnpm linkcheck checks all internal HTML links after build

Use Cases

Technical Documentation — API references, guides, tutorials
Course Platforms — Interactive learning paths with quizzes and exercises
Knowledge Bases — Internal documentation for teams
Developer Portals — Developer resources and guides

Quick Start

Prerequisites

Node.js >= 22.12.0
pnpm >= 9.0.0
Volta (recommended)

Installation

Option 1: Use GitHub Template (recommended)

Click "Use this template" at the top of the GitHub page
Give your project a name

Clone your new repository:

git clone https://github.com/yourusername/your-project.git
cd your-project

Option 2: Direct Clone

git clone https://github.com/casoon/knowledge-core.git
cd knowledge-core

After Installation

# 1. Install dependencies
pnpm install
# 2. (Optional) Customize package names# Change @knowledge-core/* to your own scope in:# - package.json files (all packages)# - Import statements in apps# 3. Start the project
pnpm dev

Development

# Start both apps
pnpm dev
# Documentation only
pnpm dev:docs
# -> http://localhost:4321# Courses only
pnpm dev:courses
# -> http://localhost:4322

Build

# Build all apps
pnpm build
# Build individual app
pnpm build:docs
pnpm build:courses

Project Structure

knowledge-core/
├── apps/
│ ├── docs/ # Documentation app (Cloudflare Pages)
│ │ ├── src/
│ │ │ ├── content/ # MDX files
│ │ │ ├── layouts/ # Astro layouts
│ │ │ └── pages/ # Pages & routing
│ │ └── package.json
│ │
│ ├── courses/ # Course platform app (Cloudflare Pages)
│ │ ├── src/
│ │ │ ├── content/
│ │ │ │ ├── courses/ # Course definitions (JSON)
│ │ │ │ └── lessons/ # Lessons (MDX)
│ │ │ ├── layouts/
│ │ │ └── pages/
│ │ └── package.json
│ │
│ └── chat-worker/ # AI chat backend (Cloudflare Workers)
│ ├── src/index.ts # RAG pipeline: embed → search → generate → stream
│ └── wrangler.toml # Vectorize + AI bindings
│
├── packages/
│ ├── ui/ # Shared UI components (incl. ChatWidget)
│ ├── styles/ # Tailwind v4 + design tokens
│ ├── content-model/ # Zod v4 content schemas
│ └── config/ # Shared configs (TypeScript, Biome)
│
├── scripts/
│ └── ingest-content.ts # Chunks & embeds docs/lessons → Vectorize
│
├── shared/ # Shared layouts, SEO, utilities
├── .env.example # Environment variable template
├── package.json # Root package
└── pnpm-workspace.yaml

AI Chat Setup

The template includes a fully functional AI assistant. After cloning, four steps are needed to activate it:

1 — Create the Vectorize index

CLOUDFLARE_ACCOUNT_ID=<your-account-id> \
wrangler vectorize create knowledge-core \
--preset="@cf/baai/bge-large-en-v1.5"

2 — Configure credentials

cp .env.example .env

Fill in .env (never commit this file):

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token # Workers AI + Vectorize permissionsCLOUDFLARE_VECTORIZE_INDEX=knowledge-core
PUBLIC_CHAT_ENDPOINT=https://knowledge-core-chat-worker.<subdomain>.workers.dev/chat

Create the API token at Cloudflare Dashboard → My Profile → API Tokens → Create Token with:

Account > Workers AI — Edit
Account > Vectorize — Edit

3 — Ingest content

pnpm run ingest

Chunks all MDX files from apps/docs and apps/courses, generates vector embeddings, and uploads them to Vectorize. Re-run this whenever you add or significantly update content.

4 — Deploy the chat worker

pnpm --filter chat-worker run deploy

The Worker is now live at https://knowledge-core-chat-worker.<subdomain>.workers.dev/chat. The ChatWidget in both apps automatically picks up PUBLIC_CHAT_ENDPOINT from your .env at build time.

Local development: run pnpm --filter chat-worker run dev to start the Worker on http://localhost:8787. No config change needed — ChatWidget falls back to this URL automatically.

Creating Content

Documentation Page

Create an MDX file in apps/docs/src/content/docs/:

---title: My Pagedescription: Descriptioncategory: guidesorder: 1tags: [tutorial]status: stable# Optional Starlight-inspired fields:draft: false # true = excluded from buildeditUrl: https://github.com/org/repo/edit/main/docs/my-page.mdxpagefind: true # false = excluded from search indexsidebar:
badge:
variant: tip # note | tip | danger | caution | successtext: Newprev:
link: /docs/introlabel: Introductionnext: false # disable next link---import { Callout } from'@knowledge-core/ui';
# My Page
<Callouttype="info">Important information!</Callout>

Creating a Course

Course definition in apps/courses/src/content/courses/my-course.json:

{
"title": "My Course",
"slug": "my-course",
"description": "Course description",
"level": "beginner",
"estimatedTotalMinutes": 120,
"tags": ["programming"],
"published": true
}

Lesson in apps/courses/src/content/lessons/:

---courseSlug: my-coursetitle: Lesson 1module: BasicsorderInModule: 1estimatedMinutes: 15goals:
- Goal 1
- Goal 2---import { Quiz, Exercise } from'@knowledge-core/ui';
# Lesson 1
<Exercisetitle="Exercise"difficulty="easy">
Task here...
</Exercise>
<Quizquestions={[
{
question: "What is 2 + 2?",
options: ["3", "4", "5"],
correctAnswer: 1
}
]}
/>

Available Components

Content Components

Callout - Info, Warning, Error, Success
CodeBlock - Syntax highlighting with copy button
Card - Content cards
Tabs / TabPanel - Tab navigation
ChatWidget - Floating AI chat panel (RAG-backed, SSE streaming)

Course Components

Quiz - Interactive quizzes with feedback
Exercise - Exercise blocks with difficulty levels
Hint - Collapsible hints
ProgressBar - Progress indicator
CourseCard - Course overview cards
LessonNav - Lesson navigation sidebar
LessonComplete - Mark lessons as complete
TotalProgress - Overall progress display
SyncProgress - Cloud sync for progress

Navigation Components

NavBar - Main navigation with mobile support & ClientRouter
SearchBar - Full-text search (Pagefind)
FontSizeControl - Accessibility font size control
QuizToggle - Show/hide quizzes

Theming

Design Tokens

Edit packages/styles/src/tokens.css:

:root {
--color-primary:#6366f1;
--color-secondary:#f8fafc;
/* ... */
}
.dark {
--color-primary:#818cf8;
/* ... */
}

Tailwind v4 Theme

Tailwind v4 uses CSS-first configuration in packages/styles/src/global.css:

@import"tailwindcss";
@import"./tokens.css";
@theme {
--color-primary:var(--color-primary);
--color-surface:var(--color-surface);
/* ... */
}
@custom-variant dark (&:where(.dark, .dark*));

Code Quality

Biome handles linting, formatting, and code analysis in a single tool. The base configuration lives in packages/config/biome.base.json and is extended by the root biome.json.

Enabled Rule Groups

Group	Scope
correctness	Unused variables/imports, exhaustive deps
suspicious	No `any`, no `var`, no `==`, no assignment in expressions
style	`const` required, template literals, no non-null assertions
complexity	Cognitive complexity limit, `for...of` over `forEach`, `flatMap`
performance	No accumulating spread, no `delete`
security	No `dangerouslySetInnerHTML`
a11y	ARIA, alt text, button types, valid anchors

Commands

pnpm check # Biome lint + format check
pnpm check:fix # Biome auto-fix
pnpm format # Format all files
pnpm lint # Lint only
pnpm type-check # TypeScript check
pnpm test# Vitest unit tests (content-model + i18n utils)
pnpm linkcheck # Build docs + validate all HTML links

Pre-Commit Hook

Husky + lint-staged runs biome check --write on staged files automatically.

Scripts

# Development
pnpm dev # All apps
pnpm dev:docs # Docs only
pnpm dev:courses # Courses only# Build
pnpm build # All apps
pnpm build:docs # Docs only
pnpm build:courses # Courses only# Preview
pnpm preview # All apps
pnpm preview:docs # Docs only
pnpm preview:courses # Courses only# Quality
pnpm test# Vitest unit tests
pnpm linkcheck # Build docs + check all HTML links
pnpm type-check # TypeScript check
pnpm check # Biome lint + format
pnpm check:fix # Biome auto-fix# AI
pnpm run ingest # Embed & upload all content to Cloudflare Vectorize# Clean
pnpm clean # Remove all build artifacts

Sidebar Configuration

The docs sidebar is configured declaratively in apps/docs/src/config/sidebar.ts:

import{defineSidebar}from'@knowledge-core/content-model/sidebar';exportconstsidebar=defineSidebar([{label: 'Getting Started',autogenerate: {directory: 'getting-started'}},{label: 'Guides',autogenerate: {directory: 'guides'}},{label: 'Reference',collapsed: true,items: [{slug: 'api/overview'},{slug: 'api/endpoints',badge: {variant: 'tip',text: 'New'}},],},{label: 'GitHub',link: 'https://github.com/casoon/knowledge-core'},]);

Deployment

Cloudflare Pages (docs & courses)

Set PUBLIC_CHAT_ENDPOINT as an environment variable in the Pages project build settings, then:

Build Command: pnpm --filter docs build / pnpm --filter courses build
Build output directory: apps/docs/dist / apps/courses/dist

Or deploy manually after a local build:

wrangler pages deploy apps/docs/dist --project-name=knowledge-core-docs
wrangler pages deploy apps/courses/dist --project-name=knowledge-core

Chat Worker (Cloudflare Workers)

pnpm --filter chat-worker run deploy

Vercel

Push to GitHub
Import on Vercel
Select root directory
Build Command: pnpm build:docs or pnpm build:courses
Output Directory: apps/docs/dist or apps/courses/dist

Netlify

# netlify.toml
[build]
command = "pnpm build:docs"publish = "apps/docs/dist"

Documentation

SETUP.md - Detailed setup guide and customization
CONTRIBUTING.md - Contribution guidelines

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

MIT License - see LICENSE

Credits

Built with Astro, Tailwind CSS, MDX, Biome, and pnpm.

Made with care for developers and educators

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
.husky		.husky
apps		apps
packages		packages
scripts		scripts
shared		shared
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
biome.json		biome.json
knowledge-core-reference.txt		knowledge-core-reference.txt
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Knowledge Core

Live Previews

Tech Stack

Features

Use Cases

Quick Start

Prerequisites

Installation

After Installation

Development

Build

Project Structure

AI Chat Setup

1 — Create the Vectorize index

2 — Configure credentials

3 — Ingest content

4 — Deploy the chat worker

Creating Content

Documentation Page

Creating a Course

Available Components

Content Components

Course Components

Navigation Components

Theming

Design Tokens

Tailwind v4 Theme

Code Quality

Enabled Rule Groups

Commands

Pre-Commit Hook

Scripts

Sidebar Configuration

Deployment

Cloudflare Pages (docs & courses)

Chat Worker (Cloudflare Workers)

Vercel

Netlify

Documentation

Contributing

License

Credits

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages