Skip to content

README.md

Latest commit

 

History

History
219 lines (153 loc) · 6 KB

README.md

File metadata and controls

219 lines (153 loc) · 6 KB
Raw

🌱 Open.Quartz

A learning journey through Quartz - rebuilding a fast, batteries-included static-site generator from the ground up.

📖 About

Open.Quartz is a copy-learning project based on jackyzha0/quartz — a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites.

This project is an educational endeavor to understand the internals of Quartz by rebuilding it step-by-step, documenting the learning process, and gaining deep insights into static-site generation, TypeScript architecture, and modern web development practices.

🎯 Learning Goals

  • Understand static-site generator architecture
  • Master TypeScript advanced typing patterns (nominal types, type guards)
  • Learn build pipeline design with esbuild
  • Explore plugin architecture and extensibility
  • Study internationalization (i18n) implementation
  • Deep dive into CLI design patterns

✨ Features

Based on the original Quartz, this project aims to implement:

  • 📝 Obsidian Compatibility - Full support for Obsidian-flavored Markdown
  • 🔍 Full-text Search - Built-in search functionality
  • 🕸️ Graph View - Visualize note connections
  • 🔗 Wikilinks & Backlinks - Networked thought support
  • 🎨 Simple JSX Layouts - Customizable page components
  • ⚡ Hot Reload - Incremental rebuilds for content edits
  • 🌍 Internationalization - Support for 30+ languages
  • 🐳 Docker Support - Containerized deployment

🚧 Progress

Current Status: 🚧 Early Development Phase

✅ Implemented

Component Status Description
Path Utilities ✅ Complete Nominal types for path safety (FullSlug, SimpleSlug, FilePath, RelativeURL)
CLI Commands ✅ Partial create, sync, restore, build commands
Build Pipeline ✅ Partial esbuild integration with cache busting
Type System ✅ Complete Plugin data type augmentation
i18n System ✅ Complete 30+ locale definitions
Testing ✅ Partial Unit tests for path utilities

🔄 In Progress

  • Content transformation pipeline
  • Plugin architecture implementation
  • Component rendering system
  • Configuration management

📋 Planned

  • Search functionality
  • Graph visualization
  • SPA navigation
  • Popover previews
  • Theme system

🛠️ Usage

📋 Prerequisites

  • Node.js v22 or higher
  • npm v10.9.2 or higher

🔧 Installation

# Clone the repository
git clone https://github.com/Open-IA/Open.Quartz.git
cd Open.Quartz

# Install dependencies
npm install

🚀 Available Commands

# Create a new Quartz site
npm run quartz create

# Build the site
npm run quartz build

# Sync with remote
npm run quartz sync

# Restore dependencies
npm run quartz restore

# Run tests
npm test

📚 Learning Documentation

Detailed learning notes are maintained in the devlogs directory:

  • [2025-12-15] - Project entrypoint and setup
  • [2025-12-16] - Command create implementation
  • [2025-12-26] - Command update implementation
  • [2026-01-04] - Command sync implementation
  • [2026-02-06] - Command build implementation

🏗️ Architecture

quartz/
├── bootstrap-cli.mjs    # CLI entry point
├── build.ts             # Build pipeline
├── cfg.ts               # Configuration management
├── i18n/                # Internationalization
│   ├── index.ts
│   └── locales/         # 30+ locale files
├── plugins/             # Plugin system
│   ├── types.ts
│   ├── vfile.ts
│   └── transformers/
├── util/                # Utilities
│   ├── path.ts          # Path utilities with nominal types
│   ├── path.test.ts     # Unit tests
│   ├── clone.ts
│   ├── ctx.ts
│   └── theme.ts

🧪 Type System

This project uses nominal typing to prevent common path-related bugs:

// Different path types are not interchangeable
type FullSlug = string & { __brand: "full" };
type SimpleSlug = string & { __brand: "simple" };
type FilePath = string & { __brand: "filepath" };
type RelativeURL = string & { __brand: "relative" };

// Type guards ensure type safety
isFullSlug("index"); // => true
isFullSlug("./abc/def"); // => false (relative path)

🤝 Contributing

This is a personal learning project, but feedback and suggestions are welcome!

  • Feel free to open issues for questions or discussions
  • Pull requests for improvements are appreciated

📜 License

MIT License - See LICENSE for details.

🙏 Acknowledgments

  • Original Quartz - jackyzha0/quartz
  • Community - Thanks to the thousands of students, developers, and teachers using Quartz

📊 Project Stats

Lines of Code TypeScript Learning

"The best way to learn is to build." - Unknown