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 )

[mojavelinux]

Nice work!

Unfortunately DockerHub does not support AsciiDoc

Agreed, this is a major annoyance. You can work around this slightly by using the Markdown-compatibility syntax supported by Asciidoctor. We do this for the Asciidoctor.js README. See https://www.npmjs.com/package/asciidoctor.js (not perfect, but better...and still future proof).

[sboekhoff]

I try to avoid doing 'workarounds' and 'half things'. That won't improve the products (here DockerHub.com or nmpjs.com). I (vote for) open tickets - if there is enough voters they might implement the feature. I made good experience with it in the past (especially GitLab is noteworthy).

Do you know if there is a ticket for 'Add support for AsciiDoc ...' for npmjs.com?

[mojavelinux]

Yes. See https://github.com/npm/newww/issues/1704