This is the base repository for previewing Kirby-formatted documentation in Joyent public repositories.
Joyent uses Kirby, a file-based CMS, to publish most of our web properties and documentation. This repository doesn't include the Joyent theme or other branding, but it is maintained as a reliable base to allow publicly previewing web content.
Where it's used:
- https://github.com/joyent/containerpilot: to preview the documentation. See CONTRIBUTING.md for instructions.
- Kirby is available in a public repo (linked to this repo via a git submodule), but it is not open source. See https://getkirby.com/buy for more information.
- The base theme is Nate Steiner's KDoc, which appears to be MIT-licensed.
- Joyent-developed materials in this repo are licensed under the terms of the MPLv2.
There are a number of arguments against Kirby, including:
- It's not properly open source
- It requires a runtime to view the pages, rather than generating static content
- It forces the use of numbered directories and exactly one
*.mdfile per directory, which is unexpected
We recognize these frustrations, but continue to use Kirby because...
- The content is all Markdown, so we're not really locked in to it (templates and fancy pages can get much more complex, but documentation is straightforward)
- It works well enough
- It makes the primary developer happy
- The directory structure actually eliminates confusion about the hierarchical structure of the site, even if it defies expectations
- Bikeshedding is easy, but identifying/developing a meaningful alternative and doing the migration is real work