Knowledge Core

Modern monorepo template for documentation and course platforms

A production-ready template based on Astro v6, MDX, Tailwind CSS v4, and pnpm Workspaces - optimized for creating technical documentation and interactive learning platforms.

Live Previews

Docs App: kc-docs.casoon.dev
Courses App: kc-courses.casoon.dev

Tech Stack

Technology	Version	Purpose
Astro	6.0	Framework — Vite Environment API, Content Collections, ClientRouter
MDX	5.0	Markdown with interactive components
Tailwind CSS	4.2	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	5.9	Strict mode throughout
pnpm	9.x	Workspaces with catalog for centralized dependency management
Node.js	>= 22.12	Runtime

Features

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
│   │   ├── src/
│   │   │   ├── content/   # MDX files
│   │   │   ├── layouts/   # Astro layouts
│   │   │   └── pages/     # Pages & routing
│   │   └── package.json
│   │
│   └── courses/           # Course platform app
│       ├── src/
│       │   ├── content/
│       │   │   ├── courses/  # Course definitions
│       │   │   └── lessons/  # Lessons (MDX)
│       │   ├── layouts/
│       │   └── pages/
│       └── package.json
│
├── packages/
│   ├── ui/                # Shared UI components
│   ├── styles/            # Tailwind v4 + design tokens
│   ├── content-model/     # Zod v4 content schemas
│   └── config/            # Shared configs (TypeScript, Biome)
│
├── shared/                # Shared layouts, SEO, utilities
├── package.json           # Root package
└── pnpm-workspace.yaml

Creating Content

Documentation Page

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

---
title: My Page
description: Description
category: guides
order: 1
tags: [tutorial]
status: stable
# Optional Starlight-inspired fields:
draft: false           # true = excluded from build
editUrl: https://github.com/org/repo/edit/main/docs/my-page.mdx
pagefind: true         # false = excluded from search index
sidebar:
  badge:
    variant: tip       # note | tip | danger | caution | success
    text: New
prev:
  link: /docs/intro
  label: Introduction
next: false            # disable next link
---

import { Callout } from '@knowledge-core/ui';

# My Page

<Callout type="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-course
title: Lesson 1
module: Basics
orderInModule: 1
estimatedMinutes: 15
goals:
  - Goal 1
  - Goal 2
---

import { Quiz, Exercise } from '@knowledge-core/ui';

# Lesson 1

<Exercise title="Exercise" difficulty="easy">
  Task here...
</Exercise>

<Quiz
  questions={[
    {
      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

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

# 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';

export const sidebar = 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

Build Command: pnpm build:docs
Build output directory: apps/docs/dist

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
Latest commit History 13 Commits
.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

Folders and files

Latest commit

History

Repository files navigation

Knowledge Core

Live Previews

Tech Stack

Features

Use Cases

Quick Start

Prerequisites

Installation

After Installation

Development

Build

Project Structure

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

Vercel

Netlify

Documentation

Contributing

License

Credits

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages