Starter template for a MkDocs docs site on GH Pages - including CI
MIT License
Starter template for a MkDocs docs site on GH Pages - including CI
A template, live demo and tutorial for how to set up a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.
MkDocs is a Python package when turns your docs directory and YAML config into a static website. No Python coding needed. Just Markdown and some light configuration including a theme choice and menu.
This project provides low-code content-focused way to set up and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.
A GitHub Actions workflow is provided with this template so you can easily deploy to GitHub Pages too.
This template project is configured to use the Read the Docs theme, as shown above.
Thus looks like the the Read The Docs site, but without having to have to overhead of using Sphinx.
This Read the Docs theme for MkDocs comes with MkDocs already, so you don't need to add to your dependencies. But you can switch to the MkDocs default or install and configure another theme.
You can switch to the default theme or install some others, based on the instructions in this template project.
This project has a site deployed to GitHub Pages.
Purposes of the site:
This repo also doubles as a template to create a new project from. Click the button at the top.
Change the content and theme to suit your needs, based on the tutorial site or the MkDocs site.
To isolate the MkDocs flow from the rest of your code, you can put the configs and the docs
folder of content inside the docs
directory. That means you end up having docs/docs
, which is okay. Just make sure you select the /docs
directory when setting up GH Pages.
If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs homepage for documentation.
This project provides a way to write your docs in markdown and build a professional-looking docs site on top of it, without having to write HTML or CSS code and using a selection of themes. While MkDocs CLI has functionality to deploy from a local command-line, this project makes deploying effortless by using GitHub Actions to build and deploy the site to a gh-pages
branch and GitHub Pages to serve the site.
Compared with Jekyll and Docsify, I found the MkDocs code is much lighter to set up and changing themes is much easier than Jekyll. Also you get the benefits SEO which Docsify doesn't have. And it includes a search bar using JS.
Submit an issue.
Or submit a code change:
cp LICENSE LICENSE-source
Released under MIT by @MichaelCurrin.