From bookdown.io:
\n\n\n\nBookdown generates DocBook-like HTML output using Markdown and JSON files instead of XML.
\nBookdown is especially well-suited for publishing project documentation to > GitHub Pages.
\nFeatures include:
\n\n
\n- \n
\nAutomatic table-of-contents generation as index pages at each hierarchy level
\n- \n
\nCustom index-page titles via JSON configuration
\n- \n
\nAutomatic numbering of page headings
\n- \n
\nAutomatic previous/next/up navigation headers and footers
\n- \n
\nMulti-page hierarchical output
\n- \n
\nLoading of remote content files via HTTP
\n- \n
\nTemplated output for theming
\n- \n
\nOverridable page processing, especially for rendering
\nBookdown can be used as a static site generator, or as a way to publish static pages as a subdirectory in an existing site.
\n
Yes, I know, there\u2019s a ton of static site generators for PHP out there already. Sculpin seems to be the big one (hi Beau!) but it\u2019s not specifically for documentation. Then there\u2019s Couscous (hi Matthieu!), which is for documentation, but it\u2019s not DocBook-like documentation.
\nBy \u201cDocBook-like\u201d, 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.
\nAnd frankly, look at the dependency listings on those two projects (Scuplin, Couscous). They\u2019re rather extensive. It that a bad thing? No, but it\u2019s not my speed. I think we we all know at this point that I\u2019m about reducing dependencies as much as possible, and those are just too much for me.
\nAlso: I can\u2019t stand YAML. I don\u2019t like YAML embedded in pages, and I don\u2019t like YAML config files. I much prefer JSON, and I don\u2019t want to add YAML frontmatter on Markdown pages.
\nSo: Bookdown. This scratches my particular itch, with very few dependencies.
\nBookdown, 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.
\nAdditionally, 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.
\nI\u2019m happy with the architecture as well. It took two weekends of experimenting, and then almost exactly a week of dedicated development, to build Bookdown.
\nThe 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.
\nEverything 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.
\nAll 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.
\nFinally, 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\u2019s something I\u2019ve 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!
\nRead the Reddit discussion about this post here.
\n" }