melopt/mkdocs
A mkdocs.org image to generate documentation
50K+
Allows us to use the mkdocs command on our projects to generate documentation.
From the command line, you can obtain an explanation on how to use with:
docker run -i --rm melopt/mkdocs
This will guide you on how to use this image effectively during your documentation writing process.
The image includes the following themes and plugins:
mkdocs
and readthedocs
;alabaster
;rtd-dropdown
: a
ReadTheDocs clone but with collapsible navigation - must have for big sites;bootstrap
;cinder
;material
;nature
.Please note that none of the plugins are active by default, you need to activate them on your mkdocs.yml
file.
MkDocs uses the Python Markdown package. This package includes a lot of useful default extensions that you can use on your wiki.
To use an extension, edit your mkdocs.yml
file and add a markdown_extensions
section with the list of extensions you want to add. For example:
markdown_extensions:
- abbr
- attr_list
- def_list
- footnotes
- codehilite
The Pygments package is installed to provide code hi-lighting to your fenced code blocks, but this requires a bit of work on your part.
You'll need to:
extra_css
configuration on your mkdocs.yml
file.Pygments styles CSS generation
To generate the CSS file, on your Dockerfile for your site, add the following line:
RUN mkdir /docs/docs/css && pygmentize -S default -f html -a .codehilite > /docs/docs/css/pygments.css
Tweak the locations of the destination file (make sure the destination folder exists), and adjust
the style and class names in the pygmentize
execution. See the
codehilite Markdown plugin for more
information on the options you have.
On your mkdocs.yml
file, add a section:
extra_css:
- css/pygment-styles.css
Make sure the path matches the file you generated on the previous section.
At the end of this proces you'll have a very tiny nginx-based image that will launch a HTTP site with your documentation.
We use a multi-stage build for this. Use the following Dockerfile
as starting point:
FROM melopt/mkdocs AS builder
COPY <your source files> /docs/
RUN /usr/bin/generate_mkdocs_site
FROM melopt/nginx-alt
COPY --from=builder /build /usr/share/nginx/docs/
The final image will be a nginx-powered static site.
_
prefix trick to hide pages from the navigation. Please note
that, based on the discussion, we do not expect this to be needed after mkdocs 1.0 is relased.
See pages refactor project for status on this.
==> UPDATE: the material design includes the fix for the _
prefixdocker pull melopt/mkdocs