ev3dev/ev3dev.github.io — pull request #13 by WasabiFan (2014-09-01 00:18:19+00:00)
Title: Add the wiki (regenerated with jekyll) to the site

Right now, this is **just a concept proposal**. Please don't merge this yet, as it is still in need of work. I would just like to get feedback on whether I should spend more time to build this or not.

In this branch, I have created a submodule copy of the wiki, and have made it render with kramdown and Jekyll (technical explanation below). I added a page for the wiki, along with a sidebar containing an index of the wiki pages (much like how it works on GItHub). Clicking on a page brings up the site-formatted page just as it does in the real wiki. You can preview the demo [here](http://wasabifan.github.io/ev3dev.github.io/wiki), or look at the code [here](https://github.com/wasabifan/ev3dev.github.io/tree/site-wiki).

So, I have a few questions:
- Forgetting about any technical limitations, would this be a feature that we would be interested in? I think it could be nice for people, but is it enough of an advantage?
- Assuming that it is considered worth investigating, would the extra initial work as well as the fact that we would have to run a script to update the copy of the wiki (explained below) outweigh the benefits?
- If the answer is 'no' for either of the above questions, would having a stripped-down version of the wiki (only the getting started and basic feature pages) be better? This wouldn't require much extra work from the more general option.

In the end, I think that this could be worth some more work (which I would be happy to do). But the sheer quantity of pages that we have, many of which would rarely be used by someone on the site, could make it fairly unwieldy; so we might want to limit it to the 10 or so important pages.

Should I continue and make everything work correctly (such as images and wiki links), or is this not something that's worth the effort?

**Technical explanation:**
The wiki is brought in as a submodule. I have written a Ruby script (rakefile) that goes through the wiki in the submodule clone, and generates a copy of each page in a different folder that includes the frontmatter that Jekyll uses to render a page. Jekyll then picks up the copied files and generates the HTML.

Because GitHub Pages disables Jekyll plugins, the script has to be run manually when we want changes in the wiki to be brought in to the website. Although this can be made simpler by making the script automatically commit and push the changes, someone still has to start it.

**Side note:** I have included style updates to the sidebar in this branch along with my additions to the site content itself. The original purpose was to make the wiki links more visible, but the new styles actually look pretty good on the project pages too. If we decide not to go forward with this, I can separate out the styles if we want them.