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

    install:
        pip3 install -r requirements.txt
    
    dev:
        mkdocs serve -a localhost:3000
    
    build:
        mkdocs build
    
    format:
        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
    
    plugins:
    - search
    
    markdown_extensions:
    - pymdownx.highlight:
        anchor_linenums: true
    - pymdownx.inlinehilite
    - pymdownx.snippets
    - pymdownx.superfences:
        custom_fences:
            - 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

      site
      
  5. Setup docs

    1. Create docs folder

      mkdir docs
      
    2. Create a sample doc docs/index.md

      # 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 11, 2023
Created: June 3, 2023