Document how to use with GitLab Pages

[mojavelinux]

Unlike GitHub Pages, GitLab Pages gives you control over the pages build (a custom CI task). That means you can run Jekyll with the jekyll-asciidoc plugin, but get all the conveniences of automatic publishing that you get on GitHub Pages. We should promote this because it can save people a lot of time.

What we need to document is:

• A link to how to setup GitLab Pages
• A sample CI configuration that includes Jekyll and the jekyll-asciidoc plugin

Here's a start:

https://gitlab.com/pages/jekyll

[mojavelinux]

Here's a detailed blog post that goes a long way towards explained how to do this.

https://about.gitlab.com/2016/04/07/gitlab-pages-setup/

[mojavelinux]

Very nice! We should definitely mention this in the README.

Technically, the gem install asciidoctor line is not required since the jekyll-asciidoc gem depends on the asciidoctor gem. I recommend adding pygments.rb (or coderay) to the container too so that a syntax highlighter is available. Pygments is preferred, if possible.

[mojavelinux]

Can I assume your instructions are for deploying a custom runner for use on GitLab.com?

[sboekhoff]

Thanks for your suggestions.

Yes, the runner is for using the CI of GitLab.com. I removed gem install asciidoctor. Unfortunately I had some problems installing pygments.rb - but I'll get it running the next days.

[mojavelinux]

I'm pretty sure you need the development tools to install the pygments.rb. That's basically stuff like the C headers and such. It depends on a few native gems. On Alpine Linux, I think that's build-base.

[sboekhoff]

Thanks for the hint with build-base (adding gcc and some other packages named in the error messages was actually not enough 😉 )

Pygments should work in the latest images https://hub.docker.com/r/boekhoff/jekyll-asciidoc/

(Unfortunately DockerHub does not support AsciiDoc -> reading the README of automated builds on DuckerHub sucks: docker/hub-feedback#709 )