Chapters

Chapters

Chapters are Markdown files in src/chapters/. Each file becomes a page on your site.

Creating a Chapter

1. Copy the template:

   cp src/chapters/_chapter-template.md src/chapters/04-my-chapter.md

2. Edit the frontmatter and content:

   ---
   title: "My Chapter Title"
   description: "A brief description of what this chapter covers."
   permalink: "/my-chapter/"
   ---
   
   Write your chapter content here using Markdown.
   
   ## Section Heading
   
   Regular paragraph text. You can use **bold**, *italic*, and [links](https://example.com).

Frontmatter Fields

Field	Required	Purpose
title	Yes	Chapter title (shown in nav, cards, and page heading)
description	Yes	Brief summary (used in search results, social shares, and chapter cards)
permalink	Yes	URL path for this chapter (e.g. /my-chapter/)

File Naming & Sort Order

Chapters must use a numbered prefix for correct ordering:

01-introduction.md
02-getting-started.md
03-advanced-topics.md
04-conclusion.md

The number prefix determines the order everywhere — the sidebar, homepage chapter list, prev/next links, and the mobile bottom bar.

Excluding Files

Files starting with _ in src/chapters/ are excluded from the build. The _chapter-template.md file uses this convention — it serves as a starter but doesn't appear on the site.

Permalink

Each chapter uses Eleventy's native permalink frontmatter field. The value should be a URL path with leading and trailing slashes:

permalink: "/introduction/"

This controls the URL directly. Use descriptive slugs that match the chapter topic — they help readers and search engines understand your content.

Where Your Chapters Appear

Your chapters show up in several places across the site:

• Homepage — Each chapter is displayed as a card with its title and description in a grid layout
• Sidebar — A list of all chapters on every chapter page, with the current chapter highlighted
• Prev/next navigation — Card-style links at the bottom of each chapter page pointing to the previous and next chapters
• Mobile bottom bar — A fixed bar at the bottom of the screen on phones with prev/next chapter links and a TOC button

Layout

All chapters automatically use the chapter layout (set via a directory data file — you don't need to specify layout in frontmatter). Here's what readers see on each chapter page:

• Chapter label — "Chapter 3 of 10" at the top, in your accent color
• Reading time — An estimate like "5 min read" based on the word count (approximately 200 words per minute)
• Chapter title — The title from your frontmatter as a large heading
• Content — Your Markdown rendered with clean typography
• Prev/next cards — Navigation links at the bottom to the surrounding chapters

Images in Chapters

Place images in src/assets/ and reference them in your Markdown:

![A golden-brown sourdough loaf](/assets/sourdough.png)

Images appear inline in your chapter content on the website. Always include descriptive alt text — it helps readers using screen readers and improves SEO.

Note: Images in the generated PDF and EPUB may not appear correctly or may render differently than on the website. If your book relies heavily on images, test the generated formats. See PDF and EPUB for more on limitations.

Reading Time

Each chapter automatically displays an estimated reading time (e.g. "5 min read") based on the chapter's word count at approximately 200 words per minute. This appears next to the chapter label at the top of the page. No configuration is needed.

Supported Markdown

Chapters support all standard Markdown features:

• Headings (## H2, ### H3, etc.)
• Bold, italic, strikethrough
• Links and images
• Ordered and unordered lists
• Blockquotes
• Code blocks (fenced with triple backticks)
• Tables
• Horizontal rules

Content Tips

• Write concise descriptions — Keep them to 1-2 sentences. They appear on the homepage chapter cards and in search results when someone finds your chapter via Google
• Start content with H2 headings — The chapter title from your frontmatter is already rendered as H1, so your content should begin with ## H2 headings. Don't use # H1 in your chapter content
• Use descriptive permalinks — /introduction/ is better than /ch1/. Good permalinks help readers and search engines
• Use descriptive link text — Write "see the sourdough chapter" instead of "click here"
• The chapter template (_chapter-template.md) is a good reference for the expected format