Turn any content pack into a gamified learning site.
Cosmos is a learning platform engine that reads structured content packs called Universes and generates full-featured gamified learning sites. Give it a Universe about any topic — AI, math, web development — and it builds a complete site with learning paths, progress tracking, badges, and achievements.
- Learning Paths — Structured sequences of topics organized into modules
- Progress Tracking — Persistent progress with localStorage (or API sync)
- Badge System — Achievements unlocked by completing topics, modules, or entire paths
- Themeable — Each Universe can define its own branding, colors, and logo
- Topic Search — Filter and find topics across all paths
- Dual Output — Static export for GitHub Pages or SSR mode with Node.js
- Responsive — Works on desktop and mobile
- Syntax Highlighting — Code blocks rendered with Shiki
- Docker and Docker Compose (recommended)
- Or Node.js 18+ and npm (for local development without Docker)
git clone https://github.com/vinimlo/cosmos.git
cd cosmos
# Place your Universe folder as a sibling directory named "universe"
# Example: ../universe/
docker compose up
# Open http://localhost:4321git clone https://github.com/vinimlo/cosmos.git
cd cosmos
# Place your Universe folder as a sibling directory named "universe"
# Example: ../universe/
npm install
npm run dev
# Open http://localhost:4321| Variable | Default | Description |
|---|---|---|
PUBLIC_MODE |
hybrid |
hybrid (SSR + API) or static (GitHub Pages) |
COSMOS_SITE_URL |
auto | Site URL for static builds |
COSMOS_BASE_PATH |
auto | Base path (e.g., /my-site) |
A Universe is a content pack that follows a specific directory structure:
my-universe/
├── _catalog.json # Root catalog (name, branding, paths)
├── trilhas/ # Learning paths (JSON)
│ └── my-path.json
├── topicos/ # Content (Markdown + frontmatter)
│ ├── _index.json
│ └── my-topic.md
└── shared/ # Assets (logo, images)
└── logo.svg
See UNIVERSE_FORMAT.md for the complete specification.
| Technology | Purpose |
|---|---|
| Astro 5 | Web framework (SSR + static) |
| Tailwind CSS v4 | Styling |
| TypeScript | Type safety (strict mode) |
| Shiki | Syntax highlighting |
| Marked | Markdown rendering |
| Docker | Development & deployment |
┌─────────────────────┐ reads ┌─────────────────────┐
│ Cosmos │ ◄──────────── │ Universe │
│ (Astro web app) │ │ (content pack) │
│ │ │ │
│ - Pages & routes │ │ - _catalog.json │
│ - Components │ │ - trilhas/*.json │
│ - Progress system │ │ - topicos/*.md │
│ - Badge engine │ │ - shared/ │
└─────────────────────┘ └─────────────────────┘
│
▼
Generated Site
(static or SSR)
Cosmos looks for a universe/ directory as a sibling folder (../universe) and loads all content from there at build time.
Contributions are welcome! Please see the Contributing Guide for details.
This project is licensed under the MIT License.