Publish a Book

How to write — or convert an existing book — into the Boring College format and get it listed on the platform.

The idea

Books on Boring College live as GitHub repositories. You write the chapters as Markdown files, add a small book.yaml manifest, and we sync it to the platform. That's it.

Because the book is a Git repo, anyone can open a pull request to fix a typo, improve an example, or add a chapter. The same workflow developers use for code, applied to learning.

Already have a book written?

If you have existing Markdown content — a long README, a blog post series, a book draft — you can convert it to Boring College format in minutes.

Option A — Use the AI transformer (recommended)

If you use Claude Code, run this inside the Boring College repo: 

/transform-book /path/to/your-book.md

It reads your file (or directory of .md files), splits on H1 headings, generates slugs, writes book.yaml and all chapter files, and reports the output path. No content is rewritten — only structure is applied.

Option B — Convert manually

  1. Split into chapter files. Each top-level # Heading in your source becomes one chapters/NN-slug.md file. The H1 must be the first line.
  2. Number the files. Prefix each filename with a two-digit index: 01-intro.md, 02-getting-started.md, etc.
  3. Write book.yaml in the repo root listing title, description, and the chapter filenames in order.
  4. Strip any YAML frontmatter from the chapter files — the syncer does not process frontmatter; the H1 heading is the title.
  5. Push to a public GitHub repo and submit (see below).

The style

A Boring College book should feel like a very good README — practical, direct, and respectful of the reader's time.

  • Short chapters. Each chapter should cover one idea or skill. If a chapter needs more than ~10 minutes to read, consider splitting it.
  • Real examples. Show actual code, commands, or output — not pseudocode or hand-wavy illustrations.
  • No padding. Skip the intro that explains what the chapter is about to explain. Just explain it.
  • Any length. A 3-chapter book is fine if it covers the topic well. A 30-chapter book is fine too. Write as much as the subject needs.

Repository structure

Your GitHub repo should look like this:

my-book/
  book.yaml
  chapters/
    01-introduction.md
    02-getting-started.md
    03-next-steps.md
  README.md

book.yaml

The manifest tells us the title, description, and chapter order.

title: "My Practical Book"
description: "A short, useful description shown in the catalog."
cover: "https://example.com/cover.png"         # optional
github: "owner/repo"                            # optional — links to source repo
exercises: "https://github.com/owner/exercises" # optional
authors:                                        # optional
  - name: "Your Name"
    url: "https://github.com/yourhandle"        # url is optional per author
chapters:
  - 01-introduction.md
  - 02-getting-started.md
  - 03-next-steps.md
  • title and description are required.
  • chapters sets the order. Only listed files are synced.
  • github, exercises, and authors are all optional and shown on the book page when present.

Advanced chapter options

Each chapter entry can be a plain filename or an object with optional overrides:

chapters:
  - 01-introduction.md          # plain string — backward-compatible
  - file: 02-setup.md           # object form
    title: "Setting Up"         # optional — overrides the # Heading in the file
    slug: setup                 # optional — overrides the slug derived from the filename
    number: 2                   # optional — sets sort order explicitly
    free: true                  # optional — marks the chapter as free/paid
  • Plain strings and object entries can be mixed freely in the same list.
  • title overrides the # Heading extracted from the Markdown file.
  • slug overrides the URL slug normally derived from the filename.
  • number sets the sort order explicitly; if omitted, the chapter's position in the list is used.
  • free controls whether the chapter is readable without purchase. If omitted, new chapters default to free and existing chapters keep their current value.

Chapter files

Each chapter is a Markdown file inside the chapters/ directory.

# Introduction

This is the first chapter. The H1 heading becomes the chapter title.

Regular Markdown works: **bold**, `code`, links, lists, tables, code blocks.

```go
fmt.Println("Hello, reader")
```

The first # Heading in the file is used as the chapter title. Everything else renders as the chapter body.

License

Books listed as free on Boring College must be open source. We recommend CC BY 4.0 for prose or MIT for code-heavy books. Include a LICENSE file in your repo.

Pre-submission checklist

  • ☐ Repo is public on GitHub
  • ☐ book.yaml is in the repo root with title, description, and chapters list
  • ☐ All chapter files are in a chapters/ directory and listed in book.yaml
  • ☐ Each chapter file starts with a # Heading on the first line
  • ☐ No YAML frontmatter in chapter files
  • ☐ A LICENSE file is present (CC BY 4.0 or MIT recommended)

How to submit

When your repo is ready:

  1. Make sure the repo is public on GitHub.
  2. Check that book.yaml is in the root and all chapters are listed.
  3. Email [email protected] with:
    • The GitHub repo URL
    • A one-line description of the book's audience

We review submissions and aim to respond within a few days. If it's a good fit we'll add it to the catalog and set up auto-sync from your repo.

Paid books are not open for public submissions at this time.