Skip to content

casoon/knowledge-core

BranchesTags

Repository files navigation

Knowledge Core

CI GitHub Template License: MIT pnpm

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

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

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)

  1. Click "Use this template" at the top of the GitHub page
  2. Give your project a name
  3. 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
---

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

# My Page

<Callout type="info">Important information!</Callout>

Creating a Course

  1. 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
}
  1. 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

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

# Clean
pnpm clean               # Remove all build artifacts

Deployment

Cloudflare Pages

  1. Build Command: pnpm build:docs
  2. Build output directory: apps/docs/dist

Vercel

  1. Push to GitHub
  2. Import on Vercel
  3. Select root directory
  4. Build Command: pnpm build:docs or pnpm build:courses
  5. Output Directory: apps/docs/dist or apps/courses/dist

Netlify

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

Documentation

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

About

Knowledge Core is a production-ready monorepo template for building documentation and course platforms with Astro, MDX, Tailwind CSS, and pnpm workspaces. It ships docs and courses apps with shared UI components, interactive exercises, dark mode, and cloud-synced progress—ideal for API docs, learning portals, or internal knowledge bases.

kc-courses.casoon.dev

Topics

template documentation typescript monorepo biome astro courses knowledge-base pnpm mdx tailwindcss zod tailwind-v4 astro-v6

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages