Paul M. Jones

From bookdown.io:

Bookdown generates DocBook-like HTML output using Markdown and JSON files instead of XML.

Bookdown is especially well-suited for publishing project documentation to > GitHub Pages.

Features include:

• Automatic table-of-contents generation as index pages at each hierarchy level

• Custom index-page titles via JSON configuration

• Automatic numbering of page headings

• Automatic previous/next/up navigation headers and footers

• Multi-page hierarchical output

• Loading of remote content files via HTTP

• Templated output for theming

• Overridable page processing, especially for rendering

Bookdown can be used as a static site generator, or as a way to publish static pages as a subdirectory in an existing site.

Yes, I know, there’s a ton of static site generators for PHP out there already. Sculpin seems to be the big one (hi Beau!) but it’s not specifically for documentation. Then there’s Couscous (hi Matthieu!), which is for documentation, but it’s not DocBook-like documentation.

By “DocBook-like”, I mean (among other things) numbered headers, auto-generated tables-of-contents on their own pages, hierarchical multi-page presentation, and the next/previous/up linking at the top and bottom of pages. Look at the Solar documentation sites for a better idea; the content on those pages was generated with DocBook.

And frankly, look at the dependency listings on those two projects (Scuplin, Couscous). They’re rather extensive. It that a bad thing? No, but it’s not my speed. I think we we all know at this point that I’m about reducing dependencies as much as possible, and those are just too much for me.

Also: I can’t stand YAML. I don’t like YAML embedded in pages, and I don’t like YAML config files. I much prefer JSON, and I don’t want to add YAML frontmatter on Markdown pages.

So: Bookdown. This scratches my particular itch, with very few dependencies.

Bookdown, although it can be used as a site generator, is only incidentally a site generator. What it really is is a page generator, with the idea that you can integrate the pages into any other site you want.

Additionally, Bookdown allows you to pull content from remote locations. This is especially interesting to me because of the decoupled nature of Aura libraries. I would like very much to keep the manual documentation on each library in the same repo as that library, then publish each alone, and as part of a collection, without having to copy files around. Bookdown remote content should allow for that.

I’m happy with the architecture as well. It took two weekends of experimenting, and then almost exactly a week of dedicated development, to build Bookdown.

The library is fully separated from the project. That means you can either run it as a project on its own, or integrate the core library into your own project and glue its services and commands into your own work.

Everything uses dependency injection through an application-specific container which helps to keep the concerns well-separated. Everything uses factories and builders, which helps to enable the dependency injection.

All the underlying processes are decoupled from each other, which should make it easy to replace them with custom processes. For example, the ConversionProcess currently uses CommonMark, but I find it easy to imagine end-users replacing that with Textile, ReStructuredText, or even a combination of conversions that examines the filename extension.

Finally, the code style is a little bit of a departure for me as well. I have previously used $snake_case variables, but I tried on purpose to use $camelCase instead, and it was not a hard switch to make. Camel-case seems more popular these days, so I may bow to common convention from now on.

I really enjoyed putting this together. It’s something I’ve wanted to see in PHP land for a long time, and I finally got the opportunity and inclination. Take Bookdown out for a test drive, see how you like it, and please feel free to provide constructive feedback!

Read the Reddit discussion about this post here.