{"id":169,"date":"2015-06-07T03:46:28","date_gmt":"2015-06-06T19:46:28","guid":{"rendered":"http:\/\/vinta.ws\/code\/?p=169"},"modified":"2026-03-19T14:01:16","modified_gmt":"2026-03-19T06:01:16","slug":"using-mkdocs-to-deploy-your-markdown-documents-on-github-pages","status":"publish","type":"post","link":"https:\/\/vinta.ws\/code\/using-mkdocs-to-deploy-your-markdown-documents-on-github-pages.html","title":{"rendered":"MkDocs: Deploy your Markdown documents on GitHub Pages"},"content":{"rendered":"<p>MkDocs is a static site generator that builds modern webpages based on your Markdown documents and a simple YAML file.<\/p>\n<p>ref:<br \/>\n<a href=\"https:\/\/www.mkdocs.org\/\">https:\/\/www.mkdocs.org\/<\/a><\/p>\n<h2>Installation<\/h2>\n<pre class=\"line-numbers\"><code class=\"language-bash\">$ pip install mkdocs<\/code><\/pre>\n<h2>Configuration<\/h2>\n<p>in mkdocs.yml<\/p>\n<pre class=\"line-numbers\"><code class=\"language-yaml\">site_name: Awesome Python\nsite_url: https:\/\/awesome-python.com\nsite_description: A curated list of awesome Python frameworks, libraries and software\nsite_author: Vinta Chen\nrepo_name: vinta\/awesome-python\nrepo_url: https:\/\/github.com\/vinta\/awesome-python\ntheme:\n  name: material\n  palette:\n    primary: red\n    accent: pink\nextra:\n  social:\n    - type: github\n      link: https:\/\/github.com\/vinta\n    - type: twitter\n      link: https:\/\/twitter.com\/vinta\nextra_css:\n    - css\/extra.css\nnav:\n  - \"Life is short, you need Python.\": \"index.md\"<\/code><\/pre>\n<p>There are more themes:<\/p>\n<ul>\n<li><a href=\"https:\/\/squidfunk.github.io\/mkdocs-material\/getting-started\/\">https:\/\/squidfunk.github.io\/mkdocs-material\/getting-started\/<\/a><\/li>\n<li><a href=\"https:\/\/mkdocs.github.io\/mkdocs-bootswatch\/\">https:\/\/mkdocs.github.io\/mkdocs-bootswatch\/<\/a><\/li>\n<\/ul>\n<p>in Makefile<\/p>\n<pre class=\"line-numbers\"><code class=\"language-makefile\">site_install:\n    pip install -r requirements.txt\n\nsite_link:\n    ln -sf $(CURDIR)\/README.md $(CURDIR)\/docs\/index.md\n\nsite_preview: site_link\n    mkdocs serve\n\nsite_build: site_link\n    mkdocs build\n\nsite_deploy: site_link\n    mkdocs gh-deploy --clean<\/code><\/pre>\n<h2>Custom Domain for GitHub Pages<\/h2>\n<p>in docs\/CNAME<\/p>\n<pre class=\"line-numbers\"><code class=\"language-properties\">awesome-python.com<\/code><\/pre>\n<p>After deploying your GitHub Page, just point your domain to the following IPs with DNS A records:<\/p>\n<ul>\n<li><code>185.199.108.153<\/code><\/li>\n<li><code>185.199.109.153<\/code><\/li>\n<li><code>185.199.110.153<\/code><\/li>\n<li><code>185.199.111.153<\/code><\/li>\n<\/ul>\n<p>ref:<br \/>\n<a href=\"https:\/\/help.github.com\/articles\/setting-up-an-apex-domain\/#configuring-a-records-with-your-dns-provider\">https:\/\/help.github.com\/articles\/setting-up-an-apex-domain\/#configuring-a-records-with-your-dns-provider<\/a><br \/>\n<a href=\"https:\/\/help.github.com\/articles\/troubleshooting-custom-domains\/#https-errors\">https:\/\/help.github.com\/articles\/troubleshooting-custom-domains\/#https-errors<\/a><\/p>\n<h2>Automatic Deployment Via Travis CI<\/h2>\n<p>You need to<\/p>\n<pre class=\"line-numbers\"><code class=\"language-yaml\">language: python\n\npython:\n  - \"3.6\"\n\nscript:\n  - cp README.md docs\/index.md\n  - mkdocs build\n\ndeploy:\n  provider: pages\n  local-dir: site\n  skip-cleanup: true\n  keep-history: true\n  github-token: $GITHUB_TOKEN\n  on:\n    branch: master<\/code><\/pre>\n<p>ref:<br \/>\n<a href=\"https:\/\/docs.travis-ci.com\/user\/deployment\/pages\/\">https:\/\/docs.travis-ci.com\/user\/deployment\/pages\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>MkDocs is a static site generator that builds modern webpages based on your Markdown documents and a simple YAML file.<\/p>\n","protected":false},"author":1,"featured_media":340,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[39],"tags":[128,10],"class_list":["post-169","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-about-misc","tag-ci","tag-github"],"_links":{"self":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts\/169","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/comments?post=169"}],"version-history":[{"count":0,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts\/169\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/media\/340"}],"wp:attachment":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/media?parent=169"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/categories?post=169"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/tags?post=169"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}