Heads up! This page uses features your browser doesn’t support. Try a modern browser like Firefox or Chrome for the best experience.

Project structure

Adding a chapter
Front matter reference
Parts and ordering
Cover page and config

This chapter shows how to add chapters to your book and order them correctly.

Adding a chapter

Every chapter is a single Markdown file inside the _chapters/ folder. The filename becomes the page’s URL:

_chapters/structure.md  →  /structure/

To add a new chapter, create a new .md file in _chapters/ and give it the front matter described below. You don’t need to set a layout — chapters are styled automatically.

Front matter reference

The YAML block at the top of each chapter defines its metadata:

---
order: 2
chapter: 1
part: "Getting Started"
title: "Project structure"
sections:
  - "Adding a chapter"
  - "Front matter reference"
---

Key	Type	Purpose
`order`	number	Sequences every page across the whole book — chapters and unnumbered pages. Drives reading order, “Next” links, and the TOC.
`chapter`	number	The chapter number shown as the “Chapter N” label. Omit it for unnumbered pages like a preface, appendix, or glossary.
`part`	string	Groups pages into a book part (a heading in the TOC).
`title`	string	The chapter title, shown in the header, TOC, and `<title>` tag.
`sections`	list	Section names used to build the in-page index, the sidebar links, and anchor URLs.

Important: the strings in sections must match your ## (H2) headings in the body. Each entry is turned into an anchor with Jekyll’s slugify filter, so "Cover page and config" links to #cover-page-and-config. If a heading and its sections entry drift apart, the link will 404 in-page.

Parts and ordering

Reading order and chapter numbers are two separate things:

order sequences every page in the book — front matter, chapters, and back matter alike. Make the numbers globally sequential (1, 2, 3 …) so pages and parts appear in the right order.
chapter is only the “Chapter N” label. Pages without it (a preface, appendix, or glossary) simply show no number.
part groups consecutive pages under a shared heading in the table of contents.

Because order is what sorts the book, you can place unnumbered pages at the start or the end — front matter before Chapter 1, and back matter such as a conclusion, appendix, or glossary after the last chapter. A part named "Preface" (or a page with no part) shows a divider instead of a part title in the table of contents.

Preface                    ← order 1, no `chapter` (front matter)
Part: Getting Started
  Chapter 1  Project structure    ← order 2, chapter 1
  Chapter 2  Writing content      ← order 3, chapter 2
Part: Customization
  Chapter 3  Customizing the look ← order 4, chapter 3
  …
Part: Appendix
  Glossary                 ← order 8, no `chapter` (back matter)

Cover page and config

The landing page is index.html. It uses layout: home and pulls everything from _config.yml:

title: "Folio"
author: "Your Name"
subtitle: "A Jekyll template for writing books"
lang: "en"

title — appears on the cover, in the menu, and in every page’s <title>.
subtitle — the tagline under the title on the cover.
author — shown on the cover and in the footer copyright line.
lang — sets the <html lang="…"> attribute (defaults to en).

The cover renders these three lines automatically and then shows the “Start reading” button and the full table of contents. The next chapter covers writing the content itself.