I recently did some investigations at work on how to keep documentation up to date. I guess we’ve all been in the situation that the documentation we have is drifting from how the actual systems/applications look like. I believe that it’s easier to keep the documentation close the the actual code, e.g by README’s in markdown, than by have them as separate confluence pages that no one remembers to keep up to date. If you are using Confluence you can create/update documentation by using the REST api, however Confluence does not accept markdown so you have two options;
- install markdown plugins (that’s available in the api)
- or convert markdown to confluence markup language
I went with the latter options since that felt a bit easier. I found this ruby gem. Unfortunately it’s installed as a gem with dependencies you might not have available and it only runs as a cli-tool which might not be ideal if you want to include this as a step in your CI/CD pipeline. I quickly hacked together a way to run this gem as a REST server instead inside a docker container, which eliminates bothersome dependencies and make’s it easier to include in your pipeline.
Yevhen Lebid's website. A Docker-powered stateless API for converting HTML, Markdown and Office documents to PDF - thecodingmachine/gotenberg.
Quick Tutorial
- Run the container by pulling the image from docker hub:
- Test the conversion (example script in ruby)
I am on Ubuntu 16.04 and not using firewall or corporate proxy server and have tried to restart Docker. The generation of documentation based on Markdown happens with/during the site phase. The doxia module manages several Markup Language Articles Related Documentation / Reference How to use. Markdown Preview Enhanced Markdown Preview Enhanced is a SUPER POWERFUL mark. Use Docker and develop inside a container.
Asciicast Demo
Complete Example
If you want to check out the complete source code you can take a look at this repo and follow the README.
Home > Docker for Markdown | Japanese
Markdown-to-HTML Conversion Web Site in Docker Container
Kobu.Com created a Docker container of a web site that dynamically converts Markdown to HTML. The Dockerfile and the source code are published thorugh github. Ready-built docker images are on Docker hub.
Kobu.Com is willing to help you build authoring and publishing environment based on Markdown and Apache. It can also help you wrap a web site or web app in a Docker container. Please contact us.
Introduction
Docker is a container style execution environment that packages all the necessary files to run an application. A container can accomodate an entire web site or web service. Therefore you don't have to do setup work such as Apache configuration.
There exists a service to host a Docker container alone such as Amazon AWS and Googe GCP.
Filter for Local, Handler for Remote
I tested two methods for Markdown rendering on Apache:
- Apache mod_external_filter-compiant filter for serving local Markdown files in a docker container or host,
- Apache mod_actions-compliant handler for serving remote Markdown files instead of local files.
The filter version is simple and suitable if you can freely manage the host machine where you run the docker container.
The handler version may be required if the web resources including Markdown source resides in another place than the docker host. This also applies a case you want to place your Markdown source files on a public cloud service such as Amazon or Google or other file storage services.
GitHub/DockerHub
Docker Markdown Download
You can get files for building a Docker container from GitHub.
If you are interested, take the github project and build and run the image as described in README.md in the project.
You can get a pre-built Docker image from the Docker Hub.
- docker-hub local & remote
Related Links
Docker Markdown Wiki
Other Links in This Site
Markdown Docker Syntax
Written 2020-Sep-14 filter version
Updated 2020-Sep-21 handler version