Add custom HTMLPipeline
Copying from gitlab-foss#18739 (comment 25486102)
Proposal
Add https://github.com/burnto/nanoc-html-pipeline to the docs project, which is essentially a Nanoc filter of https://github.com/jch/html-pipeline.
We can then extend the HTMLPipeline with our own stuff, so we can do things like:
{{#omnibus}}
Omnibus section
{{/omnibus}}
{{#source}}
Source installation section
{{/source}}
Why
We could avoid things like splitting Omnibus and source docs in areas that are hard to follow:
- Pages admin docs
- Redis HA
- Geo docs gitlab#1908 (closed).
Example implementation
We could do something like what the Atom flight manual does and have both info (Omnibus + source) that could be toggled with a button. For example, there is info on installing on all three platforms and instructions change with a click of a button:
- Rendered page http://flight-manual.atom.io/getting-started/sections/installing-atom
- Source markdown https://github.com/atom/flight-manual.atom.io/blob/6841416496887134fcbb341b6eb9effb899fc8c6/content/getting-started/sections/installing-atom.md
This seems to be achieved using the extended Markdown filter and a bit of JavaScript and a Nanoc layout:
- https://github.com/gjtorikian/extended-markdown-filter
- https://github.com/atom/flight-manual.atom.io/blob/master/nanoc.yaml#L12-L14
- https://github.com/atom/flight-manual.atom.io/blob/master/CONTRIBUTING.md
- https://github.com/atom/flight-manual.atom.io/blob/master/layouts/includes/platform-nav.html
- https://github.com/atom/flight-manual.atom.io/blob/master/assets/javascripts/platform-nav.js
Edited by Achilleas Pipinellis