• Organizing Files in Chalk

    Author Guide to Structure, Naming, and Media

    This guide explains how to structure your Chalk files as your course evolves—from rough drafts to production-ready content. The goal is to support a smooth authoring workflow while keeping things clean for previews, review, and export.

    1. Start Simple, Refine Over Time

    You don’t need a perfect structure on day one. Chalk supports evolving your files as your content matures:

    Stage Typical Setup
    Early Draft One .chalk file with an outline or multiple lessons
    In Progress One file per chunk (e.g. per lesson or guide)
    Production One folder per lesson with media colocated

    It’s okay to start loose and restructure later.

    2. Use Folders and Filenames to Set Order

    Use clear folder and file names to control the order of your content. Chalk tools infer structure from filenames—no need to duplicate it in metadata.

    Examples:

    01-unit-intro/
  01-overview.chalk
  02-key-concepts.chalk

    Or:

    01-unit-intro/
  1-1-overview.chalk
  1-2-key-concepts.chalk

    Tips:

    • Use prefixes like 01-, 1-2-, etc. to set order.
    • Hyphens indicate hierarchy (e.g. 1-2 = Unit 1, Lesson 2)
    • Zero-padding (01, 02) makes folders easier to sort.

    3. Where Media Files Go

    Media files (images, videos, motion) should live next to your .chalk file—not hidden away in a media/ folder.

    Good:

    01-bad-button/
  index.chalk
  01-screenshot.png
  02-demo.mp4

    or

    01-bad-button.chalk
01-bad-button/
  01-screenshot.png
  02-demo.mp4

    Use relative paths in Chalk:

    !!!
[Alt text]
01-screenshot.png
Caption goes here.
!!!

    Avoid:

    • Nesting media in /media/ subfolders
    • Mixing in exported or built files (keep it source-only)

    4. Add Metadata (Optional, Helpful)

    You can add metadata to help with previews, review, and publishing—but it’s never required.

    You can include it in:

    • YAML frontmatter at the top of your .chalk file
    • A meta.yaml or index.yaml file in the folder

    Recommended fields:

    title: Good Buttons
type: Lesson
author: Nevan
duration: 20 minutes

    Other optional fields:
    goals, status, version, slug, prerequisites

    For multi-page folders, keep parent index pages light, use short child title values for sidebar nav, and prefer page-name link text—see Best Practices.

    5. It’s OK to Start Loose

    In early stages, it’s totally fine to work in a single file that contains outlines, multiple ideas, or rough chunks.

    As the course takes shape, you can break things up and move to per-chunk files, then folders with media.

    6. Optional: Use version When Ready

    The version field helps track publishing and coordination milestones, but Git remains the full history.

    It’s fine to:

    • Use version: 1.0 when a lesson is finalized
    • Leave it out while drafting
    • Revert a “final” file back to draft as needed