18F / hub

DEPRECATED: Documentation hub for the 18F team
https://github.com/18F/handbook
Other
46 stars 33 forks source link

Investigate switching to Hugo #326

Open mbland opened 9 years ago

mbland commented 9 years ago

After meeting with @shawnbot and @msecret a couple weeks ago to discuss the Hub's basic premise and structure, there was the consensus that the basic architecture is sound (if in need of enhancements), but it would be really nice if building and rebuilding it was faster. To that end, I've begun to investigate switching from Jekyll to Hugo.

In addition to making the Hub more dev-friendly by tightening the edit-build-review cycle through faster build times, I'm also intrigued by Hugo's "themes" feature, which may help solve the long-standing problem we've had around how to share common style assets between projects. (Though, to be fair, perhaps we could package common style assets as a gem...)

Also, Hugo site organization seems collections-focused from the start, which is something I began experimenting with already. I'm hoping this will eventually make it easier for nontechnical folks to add and maintain content.

Early results are promising, but there's work to be done. Except for the data import/munging and private/public items, all the following are currently well underway; I'll get to pushing bits of code into public repos shortly.

cc: @afeld @meiqimichelle @gboone @bsweger @arowla

cc: @jackiekazil @ramirezg per 18F/analytics-standards#7

cc: fellow Gophers @dlapiduz @harrisj @jcscottiii

mbland commented 9 years ago

Note regarding the "private/public" mechanics: There's a configuration option called ignoreFiles (with published documentation forthcoming) that should allow us to filter out private content in public mode, a la #332.

Note regarding data import/munging: Especially now that the Hub's Jekyll collections are coming together, and Hugo's 'sections' are almost isomorphic to collections, not only is the Hub's plugin code getting pared down, but is should be relatively straightforward to replicate the Hub's data munging as a standalone script. This script could produce JSON that could both serve as input to site generation and as API data directly.

arowla commented 9 years ago

This script could produce JSON that could both serve as input to site generation and as API data directly.

W00t!