# WordPress Library: the Milestones books and the pipeline behind wordpress.org/book

> The WordPress Library repository holds the Markdown source of the Milestones books about WordPress history, and it doubles as the content pipeline that feeds wordpress.org/book, with a manifest.json mapping chapters to site posts and Python scripts that validate the manifest and rebuild the EPUB and PDF. It is a publishing repository, not a plugin, and the two volumes it contains are a ten-year retrospective and a second-decade account.

**WordPress/library** — Our book about WordPress. Volume 1, first ten years

- Repository: https://github.com/WordPress/library
- Website: https://wordpress.org/book/
- Stars: 545 · Forks: 127
- Language: Python
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/wordpress-library

## A publishing repository that also feeds a website

The WordPress Library is described as a home for books about the history and development of WordPress, where each book is a volume in the Milestones series. The repository description calls it our book about WordPress, Volume 1, first ten years, and the homepage points at wordpress.org/book.

What makes it more than a folder of text files is the second half of its job. The website wordpress.org/book shows the chapters from this repository, and the site re-imports each chapter after it changes on trunk. The edit source is the Markdown in this repository, not the site, and the README is explicit that the next import replaces edits made on the site directly.

That is a small but consequential design decision. Anyone who finds a typo on the website and fixes it in the site's own editor will lose the change, and the README says so rather than leaving it to be discovered. The repository is the single source of truth, and the website is a rendering of it.

The audience has two parts. Readers who want the history of WordPress as a book, available as EPUB, PDF and a designed print-style edition. And contributors, which the README takes seriously, with a feedback section that asks for factual corrections with links, clarity notes, omissions and images, all as issues in the tracker.

The primary language of the repository is Python, but that is because of the tooling, not the content, which is Markdown.

## manifest.json is the contract between chapters and site posts

The mechanism connecting the two halves is manifest.json. It lists every chapter file, as a URL-encoded path relative to the repository root, together with the post it fills on the site. The site re-imports each chapter after it changes on trunk.

The mapping rules are laid out in the README and they are short enough to state fully. The post title comes from the title field in the manifest, and the book title and chapter heading at the top of each file are left off the web page because the site already shows them. A new chapter needs a post on the site first, then a manifest entry with that post's slug. In other words the site owns the container and the repository owns the content, and the manifest is the lookup that says which file goes into which container.

The URL-encoding detail is worth noting. Chapter paths are stored encoded, which means a file with a space, a non-ASCII character or a special character in its name still resolves. That is what keeps the manifest mechanical rather than requiring hand-editing per chapter.

Footnotes are handled in a deliberately boring way, with standard Markdown: a [^1] marker in the text and a [^1]: The note. line at the end of the chapter. Nothing custom, so the same footnote syntax works whether a chapter is read on the site, in a local Markdown editor, or inside the generated EPUB and PDF.

## check-manifest.py runs on every pull request

There is a validation script, and the README is specific about when it runs:

```bash
python3 bin/check-manifest.py
```

The script checks the manifest and the footnotes, and it also runs on every pull request. That second point is the important one, because it means a broken manifest or a malformed footnote fails in CI rather than in production on the site, where the visible result would be a missing chapter or a footnote that silently drops out of the rendered page.

Given that the manifest is the file that maps chapters to site posts, a validation step on it is not optional bookkeeping. A wrong slug means a chapter is written into the wrong post, and a wrong path means a chapter vanishes. Neither failure is loud from the author's side, because the Markdown still looks fine in a local preview.

The script lives in a bin directory alongside the build script, so the tooling is small and self-contained. It is Python 3, invoked with the interpreter named explicitly rather than through a shebang convention or a package manager, which keeps the dependency surface to the standard library plus whatever the scripts import.

For a contributor, the workflow is simple: edit the Markdown, add a manifest entry if you added a chapter, run the check locally, and open the pull request.

## build-books.py rebuilds the EPUB and PDF from trunk

The downloadable files are generated artifacts, and the README explains their lifecycle precisely. The EPUB and PDF links rebuild from the repository every time the book changes on trunk, so they always match the text in the repository and on wordpress.org/book.

The local build is one command:

```bash
python3 bin/build-books.py
```

It needs pandoc and WeasyPrint, which the README links, and those two dependencies explain the output format. Pandoc handles the conversion to EPUB, and WeasyPrint is a CSS-based HTML to PDF renderer, which is how a book laid out in HTML with print styles becomes a typeset PDF.

The two kinds of downloadable file are not the same thing, and the difference matters. The generated EPUB and PDF are always current with trunk. The designed original editions, with their typography and MOBI files, stay in each volume's Formats/ folder, and the README warns that they do not include later fixes.

So there is a trade-off between the two. The generated files are correct and current but plain. The designed editions are typographically nicer and include MOBI for Kindle-era workflows, but they are frozen at whatever state they were last produced in. A reader who wants the latest corrected text takes the EPUB or PDF. A reader who wants the designed artifact accepts that it may be behind.

Kindle is called out separately: it reads the EPUB directly, so no conversion step is needed for that device.

## Two volumes covering the first two decades

The repository currently holds two volumes, each in its own directory.

Volume 1 is Milestones: The Story of WordPress, covering the origins of WordPress and its first decade, with the original 2015 edition kept in milestones-vol-1/Formats/. Volume 2 is Building Blocks: The Evolution of WordPress, covering the second decade including the Gutenberg project and the global pandemic, and looking at where the project is headed, with the original 2023 edition in milestones-vol-2/Formats/.

Both are available as EPUB and PDF from the releases, and both have a read-the-book link into their directory in the repository, so the Markdown source is browsable without downloading anything.

The structure of a volume directory is not documented beyond the Formats/ folder, but the existence of a Formats/ subdirectory per volume, and the manifest entries described earlier, indicate that each volume keeps its chapters, any images, and its print-ready artifacts together. A .gitignore.md file at the root of the repository suggests the project documents its own ignore rules in Markdown rather than only in the .gitignore file, which is a small touch that makes the repository layout self-explanatory to a reader browsing it.

The scope here is a deliberately limited one. This is history and documentation, not a piece of WordPress software, and nothing in the repository is a plugin, a theme, or an API you would call.

## Corrections need evidence, and the licence lets you build on it

The feedback section states the conditions for a change, and they are unusually firm for a prose project. Notes about factual errors are welcome, and all suggestions for changes should be evidenced with links that back up any claims. Any facts that cannot be corroborated will not be included. Clarity notes are wanted, particularly for sections that are technical in nature. Omissions should be accompanied by information about why the item should be included and backed up with evidence as to its importance. Images that would complement the text are welcome. All of it goes into the issue tracker.

For a history book, that evidence rule is the whole editorial policy. The alternative, a book that records what people remember, drifts into folklore within a couple of years. Requiring a link per claim keeps the text checkable by anyone who disagrees.

The licence is dual, and the README states both books are licensed under GPLv2 and Creative Commons Sharealike 4.0, with the GPL text in license-gpl.txt and the Creative Commons text in license-cc.txt at the root of the repository. The reasoning is given explicitly: just like WordPress, you are free to read, share, distribute and modify the content however you want, passing on those freedoms to everyone else.

That pairing is what lets the content live inside a WordPress-adjacent ecosystem while still being usable by anyone, including a publisher who wants to issue an edition. The sharealike obligation is the trade-off, and it applies to derivative works of the text rather than to software that merely links to it.

The repository's own licence metadata is recorded as a custom licence that GitHub cannot classify, which is a side effect of shipping two licences side by side rather than one.

## Publishing cadence and what the recent push actually changed

The last push to the repository was on 2026-10-16, and the releases list shows a single tagged entry named latest, dated 2026-10-13, which is the mechanism behind the always-current download links. The download URLs point at the latest release rather than at a version number, so the URL a reader bookmarks never goes stale.

That design has a consequence for anyone who wants to cite a specific edition. There is no v1, v2, v3 to point at, only latest, and the artifacts inside it are regenerated from trunk. The README offers the designed original editions in the Formats/ folders as the stable alternative, with their own fix history, which is effectively the only way to reference a fixed text of a given volume today.

The repository is not archived and the default branch is trunk, and the manifest re-import behaviour is tied to that branch by name, so the trunk convention is load bearing rather than a naming preference.

For anyone planning an involvement, the practical entry points are narrow and clear. Correct the text and open an issue with citations. Add a chapter by creating the site post first and then adding the manifest entry. Run python3 bin/check-manifest.py before opening the pull request, and expect it to run again in CI.

## Conclusion

Adopt the WordPress Library repository if you want to read the Milestones history of WordPress, contribute corrections with sourced evidence, or understand how a book and a website share one source of truth. Do not adopt it as a code library, since it contains no reusable API, and do not treat the downloadable EPUB and PDF as canonical, because they are rebuilt from trunk and the designed original editions in each volume's Formats folder carry their own fix history. Verify first that a pull request passes python3 bin/check-manifest.py, that any new chapter has a post on the site before you add a manifest entry, and that your corrections are backed by links, since uncorroborated facts are not accepted.

## FAQ

### What is in the WordPress Library repository?

It holds the books about the history and development of WordPress, each a volume in the Milestones series. Currently there are two: Milestones: The Story of WordPress covering the origins and first decade, and Building Blocks: The Evolution of WordPress covering the second decade, both available as EPUB and PDF.

### How does wordpress.org/book get the chapters?

The site shows the chapters from this repository and re-imports each chapter after it changes on trunk. manifest.json lists every chapter file as a URL-encoded path relative to the repository root along with the site post it fills, and the post title comes from the title field in that manifest.

### How do I build the EPUB and PDF of the WordPress books?

Run python3 bin/build-books.py, which needs pandoc and WeasyPrint installed. The generated files rebuild from the repository every time the book changes on trunk, while the designed original editions with their typography and MOBI files stay in each volume's Formats/ folder without later fixes.

### How do I add a new chapter to the WordPress books?

A new chapter needs a post on the site first, then a manifest entry with that post's slug. Footnotes use standard Markdown, with a [^1] marker in the text and the matching [^1]: note. at the end of the chapter.

### What licence applies to the WordPress books?

Both books are dual-licensed under GPLv2 and Creative Commons Sharealike 4.0, with the licence texts in license-gpl.txt and license-cc.txt. You are free to read, share, distribute and modify the content as long as you pass those freedoms on.

## Sources

- [Issues](https://github.com/WordPress/library/issues)
- [Project website](https://wordpress.org/book/)
- [README](https://github.com/WordPress/library/blob/trunk/README.md)
- [Releases](https://github.com/WordPress/library/releases)
- [WordPress/library on GitHub](https://github.com/WordPress/library)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wordpress-library