• Tools and Packages

    This repository contains several internal tools and packages that support our work. This guide provides an overview of what’s available and when to use each tool.

    Core Content Tools

    Chalk

    Location: packages/chalk/

    Chalk is our content authoring format and build system. It processes .chalk files (Markdown-based) into HTML for preview and export.

    When to use: You’ll use Chalk whenever you’re writing course content, handbook documentation, or any content in the repository.

    Documentation: See the Chalk documentation for complete details on syntax, features, and usage.

    Key commands:

    • pnpm chalk — Start Chalkboard preview server
    • cd packages/chalk && pnpm build — Build content for production

    Chalkboard

    Location: websites/chalkboard.buttonschool.com/

    Chalkboard is the preview tool for viewing Chalk content locally. It provides a web interface for browsing and previewing content as you write.

    When to use: Always use Chalkboard to preview your content changes before committing.

    Key commands:

    • pnpm chalk — Start Chalkboard dev server (from root)

    Workbench

    Location: packages/workbench/

    Workbench is an interactive UI playground for creating educational demos. It lets you build explorable interface demonstrations with configurable props, animations, and layered component views.

    When to use: Use Workbench when creating interactive demos for courses that need to show how UI components work or behave.

    Documentation: See the Workbench documentation for details.

    Key features:

    • Configurable props with controls
    • Playable animations
    • Exploded view for layered components
    • Zoom support for detailed examination

    Blueprint

    Location: packages/blueprint/

    Blueprint is a component library for building layered UI elements that work with Workbench. Components understand zoom levels, explosion states, and interactive variants.

    When to use: Use Blueprint components within Workbench demos to create layered, explorable UI demonstrations.

    Documentation: See the Blueprint documentation for component API and usage.

    Key components:

    • Element — Container for layered compositions
    • Fill — Background fills
    • Shadow — Box shadows
    • Content — Text and typography
    • Layout — Flexbox-based layouts

    Utility Tools

    Course Exporter

    Location: tools/course-exporter/

    A tool for exporting course content as zip files, including both source and built versions.

    When to use: Use when you need to package a course for distribution or backup.

    Key commands:

    • pnpm export aui — Export Advanced UI course
    • pnpm export af — Export Advanced Figma course

    Invoice Downloader

    Location: tools/invoice-downloader/

    An internal Python tool for automatically downloading invoices from various providers (Stripe, Netlify, Veed, etc.).

    When to use: Internal tool for managing invoices and billing.

    Setup: Requires Python environment and service account credentials.

    Internal Apps

    These are standalone internal applications in apps/:

    Hub

    Location: apps/hub/

    Internal ops hub for Button School.

    Key commands:

    • pnpm hub — Start dev server (from root, with live env)

    Launch Desk

    Location: apps/launch-desk/

    CMO mission control for cohort launches.

    Key commands:

    • pnpm launch-desk — Start dev server (from root, with live env)

    Leads

    Location: apps/leads/

    Preview lead outreach tool.

    Key commands:

    • pnpm leads — Start dev server (from root, with live env)

    Feedback

    Location: apps/feedback/

    Cohort-configurable app for reviewing student submissions and sending feedback emails.

    Key commands:

    • pnpm feedback — Start dev server (from root, with live env)

    School Planner

    Location: apps/school-planner/

    A course planning tool built with Svelte for organizing and planning course content.

    Key commands:

    • pnpm planner — Start dev server (from root)

    Project Board

    Location: apps/project-board/

    Kanban-style project management tool.

    Key commands:

    • pnpm board — Start dev server (from root)

    Dashboard

    Location: apps/dashboard/

    An analytics dashboard built with Observable for viewing revenue, sales, and student feedback data.

    When to use: Internal tool for viewing business metrics and analytics.

    Lab Tools

    These are generators, exporters, and experimental tools in lab/:

    Quick Command Reference

    Common commands you might use:

    # Content preview
pnpm chalk              # Preview all content
pnpm handbook          # Preview handbook only

# Internal apps
pnpm hub               # Run ops hub
pnpm launch-desk       # Run launch desk
pnpm leads             # Run leads tool
pnpm feedback          # Run feedback tool
pnpm planner           # Run school planner
pnpm board             # Run project board

# Development
pnpm install           # Install all dependencies

# Export
pnpm export <course>   # Export a course as zip

# Individual packages
cd packages/chalk && pnpm dev
cd packages/workbench && pnpm dev

    When to Use Which Tool

    Writing course content?

    • Use Chalk to write .chalk files
    • Use Chalkboard to preview (pnpm chalk)

    Creating interactive demos?

    • Use Workbench to create the demo
    • Use Blueprint components for layered UI elements
    • Preview in Chalkboard

    Working on internal apps?

    • Check package.json at the root for shortcut scripts (most apps have one)
    • Or navigate to the app directory and run pnpm dev

    Working on shared packages?

    • Navigate to the package directory
    • Check the package’s package.json for available scripts
    • Run pnpm dev or pnpm build as needed

    Building generators or experimental tools?

    • Create or work in lab/ directory

    Getting Help