Documentation Files to AsciiDoc
I was thinking of converting all the repository documentation files to GitHub flavoured markdown, so they could be more readable on GitLab's Web UI and could also be easily reused for the Wiki or other docs.
If I understand correctly, you are using a plaintext format so that they can be included in the GUI's controls as they are and look clean, without any markup syntaxes.
Pandoc to Convert from MD to Plaintext
In another project I had the same situation, and discovered that pandoc also supports a plaintext output format and a markdown (or AsciiDoc, etc) document can be automatically converted to plaintext. I also created some pandoc filters to handle conversion of some elements, for example converting level 1 headings so that they have a line with 80
-s above and below; therefore the current formatting could be reconstructed in the plaintext version of the doc files — by the way, pandoc filters can be written in Lua.
So, we could maintain the documentation source files in a format which is nicely previewable on GitLab, and use pandoc with automated scripts to convert them also to plaintext version, which could be used for inclusion by the GUI. Example:
README.md— source file.
README— auto-converted plaintext version.
README_REGEX.md— source file.
README_REGEX— auto-converted plaintext version.
Autogen Website via GitLab Pages
As an added bonus, having the docs in a lightweight markup format (GFM, MD, AsciiDoc, ReSt, etc.) would also allow to benefit from GitLab Pages' free website service. All we'd need is to store the website files in a
public subdirectory of the project:
The scripts could handle updating the files in
public too, and we could put them there either as HTML converted files, and use GitLab Pages as a static file, or we could put them in AsciiDoc (or similar) and leverage instead one of GitLab's many dynamic website engines.
In the latter case, the files in the
public folder could be the originals, in AsciiDoc format (which has more formatting features), and these could then be converted to markdown and plaintext and copied to the project's root.
We'd only need to add in
public a file for the homepage, providing a brief intro and links to the other docs. The website engine (or pandoc template) will take care of adding menus and links back to the home page. I've done this before.
Anyhow, I could carry out some tests in my fork of Highlight, so I can enable GitLab pages and test how it works.
What do you think? Would you be comfortable with having to switch to markup format like Markdown or AsciiDoc for maintaining the documentation?
I think that having the documentation and website together in the same project is quite cool, as there's never the risk of the website lagging behind the latest release.