Skip to content

MkDocs documentation

This technote is built by Mkdocs.

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file (see Project Layout).

More detail about this tool at MKdocs.

Others popular static site generator site platform:

  • Pelican (suggested by Nguyễn Đăng Sơn - ESRC K53)
  • Sphinx (I have tried to use, but faced errors - not fixed yet when publishing in Github Page)

Getting started

  • mkdocs new [project name] - Create a new project

Deploy in Github Page

This document will be published in Github Page. To do this, you need:

  • Create a repository in github with name: vutang.github.io
  • Clone this repo to local machine
  • In local machine, use command:
    mkdocs gh-deploy --remote-branch master --config-file [directory to mkdocs.yml]

Test with local webserver

  • use mkdocs serve to run local web server
  • in your browser, access http://127.0.0.1:8000

Commands

  • mkdocs new [dir-name] - Create a new project.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs help - Print this help message.

Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

Support Themes

The list of supported themes for Mkdocs can be found here.

  • Readthedocs: readthedocs
  • Material: material
  • Readthedocs-DropDown: rtd-dropdown - trying but not really successful by now, need to figure out what happens

Material

Material is a theme for MkDocs, an excellent static site generator geared towards project documentation. It is built using Google's Material Design guidelines.

To install Material theme for Mkdocs: sudo pip install mkdocs-material. Follow instructions in here.

Getting started

Images

References

Mkdocs Wiki

Document rules

  • Suitable picture size is: 300x200.
    Use GIMP for scaling figures (follow the instructions in Photos/ResizingPhotos from help.ubuntu.com).
  • This document is written in both Vietnamese and English.