Docker Markdown

Posted on  by admin

Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommended using docker.

Home Docker for Markdown Japanese. Markdown-to-HTML Conversion Web Site in Docker Container.

In case you're running into problems, consult the troubleshooting section.

  1. Docker specifies the contents of this environment including installed Python and R packages using what is known as an image. Every Notebook version you create is associated with a Docker image. By default for new notebooks, this will be the latest version of the default Python or R images that we maintain at Kaggle.
  2. How to get started using Docker Hub, search and pull down Docker images, and create your own repositories.

Installation¶

with pip¶

Material for MkDocs can be installed with pip:

This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.

Markdown

with docker¶

The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Pull the image for the latest version with:

The mkdocs executable is provided as an entry point and serve is the default command. If you're not familiar with Docker don't worry, we have you covered in the following sections.

The following plugins are bundled with the Docker image:

How to add plugins to the Docker image?

Material for MkDocs bundles useful and common plugins while trying not to blow up the size of the official image. If the plugin you want to use is not included, create a new Dockerfile and extend the official Docker image with your custom installation routine:

Next, you can build the image with the following command:

The new image can be used exactly like the official image.

with git¶

Material for MkDocs can be directly used from GitHub by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:

The theme will reside in the folder mkdocs-material/material. When cloning from git, you must install all required dependencies yourself:

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.

Quick Tutorial

Docker Markdown
  • Run the container by pulling the image from docker hub:
  • Test the conversion (example script in ruby)

Asciicast Demo

Docker Markdown

Complete Example

Docker markdown server

Docker Markdown Viewer

If you want to check out the complete source code you can take a look at this repo and follow the README.