• 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

    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