Choose and implement a simple build/template process?

[snostorm]

Soon, the project will need more than 1-2 pages and a consistent look. With that we'll likely benefit from some sort of build process we can document for contributors in the project's ./README.md.

My recommendation is the builds (for now) happen locally with the static output committed in to the master repo, to support the build process already in place via #18. Later we could work with the build team to automate some things here.

If you take a look at https://www.staticgen.com/ there's a list of static-site generator tools we can pick from. Note, there is an option to filter it to only the JS-based projects (I couldn't hyperlink the filtered list directly.)

Some of the top projects by Github popularity/forks (with 2.1K - 3.8K stars each) include:

• http://hexo.io;
• http://brunch.io;
• http://metalsmith.io;
• http://harpjs.com; and
• http://assemble.io/

I need to refresh myself on these projects as it is been a couple of years since I've needed to chose one and the list has grown considerably, but overall I'd recommend us choosing a solution which offers a few simple page-template variations combined with markdown or a dead simple alternative for content.

A simple way of writing content (say in GitHub-flavoured markdown) will make it VERY easy for contributors to help us build guides, version release notes, open governance/contribution articles, etc.

Thoughts?

[snostorm]

Complication:

The current project structure assumes the root folder of the master branch is where our static files live. Thus, it gets awkward to mix-and-match our build tool / package.json / public files, etc. all in the root directory.

Options:

1. Use a gh-pages style approach whereby the master branch contains the source/tools (and possibly a compiled dist folder) and another branch contains the latest static assets to be served.
2. Coordinate with the build team to serve the website out of a sub-directory in the project, say dist or public. That way, Metalsmith/Hexo/whatever's configuration, as well as source markdown/HTML-partials/templates/etc. files could co-exist in the same branch.

I am leaning toward option 2 as it is the easiest to manage.

On a semi-related topic, it seems we've moved away from GitHub.io hosting although a copy of the site runs there too. Perhaps this repo should simply be called website or iojs.org?_

[Fishrock123]

This project will be renamed if we host it elsewhere. It only makes sense.

[Fishrock123]

I'm still leaning to a simple js file. Just needs a markdown parser and something like handlebars. I may be wrong here.

I guess we could use something like gulp of we want to also do stylesheets alongside that? I dunno.

@rvagg how should we pick up the build info, should this read it, or should we get it piped in via args or something?

cc also @zeke @mikeal

[rvagg]

@Fishrock123 perhaps if the build process was fed an argument or environment variable that gave a path to the /dist/ version of this? https://iojs.org/download/nightly/index.json it'll be on disk.

[snostorm]

It depends on if we want to have contributors version control the dist/ output or not. It certainly makes it easier to deploy and for people to clone and view the site locally if we do. (But, it is also an extra step to remember.)

Re: "simple script + parser", many of the existing npm libraries (some of which I linked to above) are slim and basically give you that functionality with minimal overhead. Maybe tomorrow I can whip up a proof of concept with Metalsmith** to show how light it would be.

If we start grouping content like blog/announcement, a guides section, etc. we'll soon be reinventing the wheel versus using a solution already maintained in the community.

Regardless we move over master to having some sort of generator process in place with template(s), it will be MUCH nicer to review/create content-related PRs.

** I like that Metalsmith is all mix-and-match plugins. Similar to using Grunt/Gulp in that sense. We can mix-and-match modules to suite our needs and adding our own custom logic/step (if needed down the line) would be simple enough.

[Fishrock123]

Metalsmith feels like a gulp that people won't be familiar with.