Build Tools

This project uses a combination of tools to build the static site and manage dependencies. Understanding them is key to customizing the project and contributing effectively.

Core Build Tools

Common Build Commands

Here are the most common commands you’ll use during development:

Development

• npm run docs or bun run docs: Starts the Quartz development server with hot-reloading at http://localhost:8080. This is the primary command for writing content.
• bun install: Installs all necessary dependencies defined in package.json.

Building

• npm run build or bun run build: Performs a production build of the site, outputting to the public/ directory.
• npm run build:strict: Validates all links before building. Used in CI/CD pipelines to ensure quality.
• npm run compact-report: Builds the site and generates a compact knowledge graph report for AI analysis.

Validation

• bun run scripts/validate-content.ts: Validates all markdown files for proper frontmatter and formatting.
• bun run scripts/validate-links.ts: Checks all internal links for broken references.
• npm run check-links: Pre-build link validation (called by build:strict).

Build Process Overview

1. Content Discovery

Quartz scans the content/ directory for all Markdown files, respecting the ignore patterns defined in quartz.config.ts.

2. Transformation Pipeline

Content passes through a series of transformers:

• FrontMatter: Extracts YAML metadata
• ObsidianFlavoredMarkdown: Processes wiki-style [[links]]
• GitHubFlavoredMarkdown: Handles tables, task lists, and strikethrough
• SyntaxHighlighting: Applies GitHub-themed code highlighting
• CrawlLinks: Builds the content graph for navigation

3. Output Generation

Emitters create the final static files:

• ContentPage: Individual HTML pages for each Markdown file
• ContentIndex: Generates contentIndex.json for search and graph visualization
• TagPage: Creates tag-based navigation pages
• FolderPage: Builds directory listing pages

4. Static Assets

The build process also:

• Bundles CSS and JavaScript
• Optimizes images and fonts
• Generates social media preview cards
• Creates the interactive graph visualization

Quartz Configuration

Site Configuration (quartz.config.ts)

configuration: {
  pageTitle: "Claude Code Research",
  enableSPA: true,              // Single Page App navigation
  enablePopovers: true,         // Preview on hover
  baseUrl: "script-kit.github.io/claude-research",
  ignorePatterns: ["private", "templates", ".obsidian"],
  defaultDateType: "modified",   // Shows last update date
}

Build Output

After building, find:

• public/: Complete static site ready for deployment
• public/static/contentIndex.json: Content graph and metadata
• public/index.html: Entry point
• public/static/: Bundled assets (CSS, JS, fonts)

Development Workflow

1. Local Development

# Start development server
npm run docs
 
# In another terminal, run validation
bun run scripts/validate-content.ts

2. Testing Changes

# Build locally to test
npm run build
 
# Serve the built site
npx serve public

3. Pre-Push Validation

The project includes git hooks that automatically validate content before pushing:

• Checks frontmatter requirements
• Validates link integrity
• Ensures proper formatting

To set up hooks:

bun run scripts/setup-validation.ts

CI/CD Pipeline

GitHub Actions automatically builds and deploys the site:

1. Trigger: Push to main branch
2. Environment: Node.js 22 with Bun
3. Build: npx quartz build
4. Deploy: Publishes to GitHub Pages

See .github/workflows/deploy.yml for the complete pipeline.

Troubleshooting Build Issues

Common Issues

Build fails with “Module not found”

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

Links validation errors

# Run link checker to see details
bun run scripts/validate-links.ts

Frontmatter validation failures

# Check specific file
bun run scripts/validate-content.ts | grep "filename.md"

Build Performance

To optimize build times:

1. Use npm run docs for development (incremental builds)
2. Exclude large directories in .gitignore
3. Run build:strict only in CI/CD
4. Use the compact report for quick overview

Advanced Topics

• Creating Custom Quartz Plugins
• Build Optimization Techniques
• Knowledge Base Architecture
• Deployment Guide

Related Resources

• Quartz Documentation
• Bun Documentation
• Configuration Reference
• Development Practices