Rendering a GitHub wiki on a GitHub Pages Jekyll site

13
votes

I have a repository with a wiki full of over 80 pages. I want to render an index of all the wiki pages on the Jekyll (GitHub Pages) site for the project, as well as render each page on the site using a custom layout, and using the styles of the rest of the site.

To do this, my first instinct was to use git submodules to include the pages from the wiki (which GitHub exposes as a git repo) in the Jekyll site's repo. But that's as far as I got: As far as I can tell, there is nowhere that Jekyll will accept markdown files that don't conform as a post. They aren't named with a date, and they don't have any frontmatter, so Jekyll just ignores them.

To get around this, I would normally just write a plugin to do what I wanted. But because the site is hosted on GitHub pages, it won't allow any plugins that I create.

So, I really don't know how to proceed. Is it even possible without custom plugins?

1
gitgithubjekyllgithub-pages

1 Answers

9
votes

The idea is :

  1. download my plugin
  2. read the docs
  3. install and rake
  4. drink a beer

What the raketask/plugin are doing once installed and configured (5 minutes) :

  1. rake wikisub add a git submodule pointing to your wiki. Must be a public wiki but can be on another repository
  2. copy and transform downloaded wiki pages as markdown with yaml front matter
  3. build Jekyll, then the plugin intercept wiki pages links conversion to transform them as Jekyll links
  4. order pizzas

For now the only problem (or not) is that Kramdown doesn't do well with Github markdown. You have to switch to redcarpet.

Two other tasks are available :

  • rake wikibuild : rebuild wiki pages

  • rake wiki : synch wiki page, build and optionally push change to Jekyll repository

Et hop!