Skip to content

Create a Documentation Site

This guide will bootstrap a documentation site with the following features:

  • Built using MkDocs and MkDocs Material
  • Published to Vercel
  1. Create a Makefile to define some common commands

        pip3 install -r requirements.txt
        mkdocs serve -a localhost:3000
        mkdocs build
        prettier --write .
  2. Create a requirements.txt file to manage Python dependencies, updating version numbers to their latest versions

    mkdocs == 1.4.2
    mkdocs-material == 9.0.12
  3. Define a mkdocs.yml configuration file

    site_name: My Site Name
    site_author: My Name
    site_url: https://<url>
    site_description: My site description
    - search
    - pymdownx.highlight:
        anchor_linenums: true
    - pymdownx.inlinehilite
    - pymdownx.snippets
    - pymdownx.superfences:
            - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_code_format
  4. Configure Prettier

    1. Install Prettier globally

      pnpm i -g prettier
    2. Configure .prettierrc

    3. Configure .prettierignore

  5. Setup docs

    1. Create docs folder

      mkdir docs
    2. Create a sample doc docs/

      # Hello world
  6. Publish to Vercel

    1. Open the create new page
    2. Select the Git repo to use
    3. In "Configure Project", select:
      1. "Framework Preset" to "Other"
      2. "Build and Output Settings" 1. "Build Command" to mkdocs build 2. "Output Directory" to site 3. "Install Command" to pip install -r requirements.txt Vercel config example

Last update: August 5, 2023
Created: May 27, 2023