Building project documentation from Markdown files

Publish on GitHub

The mkdocs build command generates a ready-to-publish static documentation site that you can upload to a remote server. To optimize the publishing process, you can create a shell script that uses rsync to push changes to the remote server every time you rebuild the documentation.

MkDocs has yet another clever feature that further simplifies the task of publishing documentation. If you happen to use GitHub, you can use MkDocs to deploy documentation to GitHub Pages. To do this, switch to the documentation project repository and run the mkdocs gh-deploy command. This publishes the documentation in the gh-pages branch of the project. That's all there is to it.


MkDocs is not the only documentation publishing tool out there. But if you need a solution that is easy to master, provides all basic capabilities right out of the box, and can grow with your needs, you should give MkDocs a try.

The Author

Dmitri Popov has been writing exclusively about Linux and open source software for many years. His articles have appeared in Danish, British, US, German, Spanish, and Russian magazines and websites. You can find more on his website at

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Static Website Generators

    If you only want to put a blog, technical documentation, or a web business card online, static website generators can save you a lot of work.

  • Tutorials – Markdown

    Create attractive and structured documents from the comfort of your text editor – and convert them to a huge array of formats.

  • Workspace: Markdown Tools

    From note-taking applications to wikis – there are plenty of handy tools for working with Markdown-formatted content. Here are a few worth adding to your toolbox.

  • Zim

    Organize your ideas, notes, and shopping lists with Zim, a handy tool that enshrines the principle of the wiki on your Linux, Mac OS, or Windows desktop.

  • Personal Knowledge Managers

    Obsidian helps you think and work more effectively by giving you a tool to record, connect, and catalog your ideas and related notes.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More