A couple weeks ago, I wrote about how I was testing Gulp tasks for an in-progress rebuild of Armadillo, my static site generator (that actually powers this site!). Last time I did this, I promised a full write-up on Armadillo, which I swear I wrote (in fact was just looking for it) but looks like I never did. So, consider this that writeup!
What is Armadillo
I’ve got a mantra when it comes to building open-source projects: pick a name, make the ASCII art, start coding. Armadillo here’s proof.
Armadillo started back in May 2013 as a Yeoman generator for scaffolding out a Grunt-based static site generator. It was one of my earliest Node projects.
Today, Armadillo is still a static site generator, but it’s evolved to be a set of composable Gulp plugins and tasks that can be configured and used as-is, or can be brought in to another Gulp project as the basis for doing static site generation. Because it’s Gulp, Armadillo can be extended with any and all of the goodies available to the Gulp ecosystem.
What Does Armadillo Do?
Armadillo, when using the default config, takes static files, compiles those that it needs to, and spits out a static site.
Static assets, like videos (
videos), audio (
audio), fonts (
fonts), and documents (
docs), all get copied directly to a folder of the same name.
Images get run through image optimization and get placed in the
Sass gets watched from the
sass directory, linted using Sass Lint, and compiled using Node Sass with Eyeglass to allow for Sass NPM modules to be used!
Armadillo supports two different ways of producing markup: either by writing HTML, or by writing GitHub Flavored Markdown (my preferred Markdown syntax). Both support front matter for defining variables to be passed in to the actual page render.
Markdown previously was rendered with Marked, which I love, but found hard to extend as I wanted to, and feels very much like it’s in maintenance mode. For Armadillo 3, I’ve switched to Remarkable which is very fast and has support for a plugin system, which I put to use to extend it a little. The documentation is lacking, but it’s working well so far. One of the extensions I’ve written is to have the rendered syntax highlighting be done through Prism, with proper
code wrapping, reducing the need to have to run it in browser.
Templating for markup rendering is done through Nunjucks. Nunjucks has been my go-to templating engine of choice since Swig was discontinued, and I explored switching to Twig for Armadillo 3, but ultimately decided that Nunjucks still reigns supreme in the token-based Node templating languages for my needs, so it’s here.
Full documentation of markup rendering extensions can be found in the Armadillo Additions section of Armadillo’s documentation.
Armadillo uses Browsersync to run its development server, allowing for automatic code injection, navigation and scroll sync, and testing on actual devices, all out of the box. This means more accurate cross-browser cross-device development that only requires an open URL.
What A Fast Armadillo
One of my goals for Armadillo, starting with the previous version, is to automate much of the work that goes in to making a super fast site. In Armadillo 2, that meant including Critical to automatically extract and inline above-the-fold CSS and load the remaining CSS asynchronously. This goes a very long way to producing a fast First Meaningful Paint and Time to Interactive, two key metrics for looking at Load in RAIL Performance Measurement.
I currently use Armadillo for two things right now: this here blog, and creating web-based presentations. The later has become quite an interesting use-case for me, and I’d like to see if I can make Armadillo easier to use for when I’m doing so. That may mean extending the newly-updated Armadillo Yeoman Generator (which needs some testing and semantic release love) or something else; not quite sure.
Since “finishing” Armadillo 3.0 3 days ago, I’ve already released 6 point releases with new functionality (yay automated semantic release!), but now my issue queue is empty so I’d love to hear ideas as to how to improve my little Webadillo (right? yah? sure.). Moving documentation from the wiki to an actual site is likely the first step after working out a better way to deploy to GitHub Pages than the current shell script I’ve got. For now, though, I’m very happy with the current state of the codebase, so get out there, use it, and leave me some feedback!
To get started with Armadillo, the easiest thing to do is use the Yeoman generator. Be sure that Node 6+ is being used, and run the following from the command line:
Install Yeoman and the Armadillo generator globally
Run the Armadillo generator
Follow the on-screen instructions. Once the project is scaffolded out, move in to that folder in the command line, and run the following:
This will kick off the build to get Armadillo up and running!