“When I ask myself ‘what would have the most impact today?’ I sit down and write documentation.”
— Miguel de Icaza
Documentation has been a big part of my career; working on Microsoft Learn, as the docs engineer for Xamarin, writing books, and building the CMS that my site has been hosted on over the years ... the act of writing has always been important to me, and whether the tools help or hinder that process. Exciting things happening on that front from Wilderness Labs via Chloroplast, an open source static HTML generator built in .NET, designed to make publishing and maintaining docs easy for teams of any size.
It’s available right now on NuGet as Chloroplast.Tool, and a custom GitHub Action I just recently contributed, that makes continuous publishing dead simple.
- Generate static HTML from markdown (including images, styles, etc.).
- Built-in template system to get you started quickly using Razor.
- Automatic sitemap generation for SEO.
- Local preview with
hostcommand (or, you can host and test using whatever other mechanism you'd like ... it's just static html after all). - One-click CI/CD publishing via the custom GitHub Action, letting you publish to Github Pages or any other static host you'd prefer.
Getting Started in Minutes
You can find all the details over on the full docs (published itself with Chloroplast) here wildernesslabs.github.io/Chloroplast. But getting started is real easy.
dotnet tool install Chloroplast.Tool -g
Then, you can easily bootstrap a new site using the built-in template:
chloroplast new conceptual MyDocs
cd MyDocs
chloroplast build
chloroplast host
The build command of course does the work of actually generating the content itself ... and you can pass in parameters to make it easy to incorporate into your CI/CD scripts
chloroplast build --root path/to/SiteConfig/ --out path/to/out
And I wanted to make that part of it easier ... so I built a ready-to-use GitHub Action so you can build and deploy docs automatically. I did that because I was working on a fun little sideproject called modulator and wanted to publish docs for the library using Chloroplast
- name: Build Docs with Chloroplast
uses: joelmartinez/chloroplast-docs-action@main
with:
rootpath: docs
outpath: docsout
From there, you can upload and deploy to GitHub Pages using the standard actions/upload-pages-artifact and actions/deploy-pages steps. Feel free to take a peek at how the modulator library's workflow works:
https://github.com/joelmartinez/modulator/blob/main/.github/workflows/build-and-deploy.yml
I'd love to see more open source make its way out there in the open source community ... and hopefully this could be a mechanism to help the community do so 🙏🏼