MkDocs Material Template

This is a template repository for documentation, wiki, knowledge base and technical blog using Material for MkDocs.

✨ Features

• MkDocs Material
• Wiki/Knowledge base
• Technical blog
• Documentation
• Markdown support
• Static site generator
• Project Structure
• Boilerplate/Template
• Best Practices
• Configuration
• Scripts
• CI/CD

🧩 Template

• You can use this template repository as reference to create a new repository with the same structure or clone the repository to start a new project. It will help you to organize your project structure and files. It works out of the box for most of the documentation projects.

• You can customize (remove, modify or add) the files and directories as needed to meet your project requirements.

• If you want to use the template repository directly, just click the Use this template button and follow the instructions.

• You can use cookiecutter to generate a new project from cookiecutter branch:

  # Clone the cookiecutter branch:
  git clone -b cookiecutter https://github.com/bybatkhuu/docs.mkdocs-template.git
  
  # Install cookiecutter:
  pip install cookiecutter
  
  # Generate a new project from the cookiecutter template:
  cookiecutter -f ./docs.mkdocs-template

---

🛠 Installation

1. 🚧 Prerequisites

• Install Python (>= v3.10) and pip (>= 23):
  • [RECOMMENDED] Miniconda (v3)
  • [arm64/aarch64] Miniforge (v3)
  • [Python virutal environment] venv

[OPTIONAL] For DEVELOPMENT environment:

• Install git
• Setup an SSH key (video tutorial)

2. 📥 Download or clone the repository

2.1. Prepare projects directory (if not exists):

# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects

2.2. Follow one of the below options [A], [B] or [C]:

OPTION A. Clone the repository:

git clone https://github.com/bybatkhuu/docs.mkdocs-template.git && \
    cd docs.mkdocs-template

OPTION B. Clone the repository (for DEVELOPMENT: git + ssh key):

git clone [email protected]:bybatkhuu/docs.mkdocs-template.git && \
    cd docs.mkdocs-template

OPTION C. Download source code:

1. Download archived zip file from releases.
2. Extract it into the projects directory.

3. 📦 Install dependencies

# Install 'mkdocs-material' and other dependencies:
pip install -r ./requirements.txt
# Or for DEVELOPMENT (with extra dependencies):
pip install -r ./requirements/requirements.dev.txt

4. 🏁 Run the documentation server locally (for DEVELOPMENT)

mkdocs serve -a 0.0.0.0:8000
# Or:
./scripts/docs.sh

5. 🌐 Check the documentation in web browser

• http://localhost:8000

6. 🏗️ Generate the HTML documentation files (static site)

mkdocs build
# Or:
./scripts/build.sh

# Check the generated HTML files (it should be in the `site` directory):
ls -al ./site

7. 🚀 Deploy the documentation

# Copy the generated HTML files to the web server:
cp -r ./site/* /var/www/docs.example.com/public
# Or use rsync:
rsync -av --delete ./site/ /var/www/docs.example.com/public/

# Or deploy the documentation to GitHub Pages (default branch: gh-pages) of this repository:
mkdocs gh-deploy --force
# Or use mike with versioning:
_major_minor_version="$(./scripts/get-version.sh | cut -d. -f1-2)"
mike deploy -p -u ${_major_minor_version} latest
mike set-default -p latest
# Or:
./scripts/build.sh -p

👍

---

📑 References

• https://squidfunk.github.io/mkdocs-material
• https://squidfunk.github.io/mkdocs-material/getting-started
• https://www.mkdocs.org
• https://pypi.org/project/mkdocs-material
• https://github.com/mkdocs/catalog
• https://github.com/jimporter/mike
• https://mkdocstrings.github.io
• https://lukasgeiter.github.io/mkdocs-awesome-nav
• https://oprypin.github.io/mkdocs-literate-nav
• https://github.com/bharel/mkdocs-render-swagger-plugin
• https://blueswen.github.io/mkdocs-swagger-ui-tag