Skip to content

Getting Started

This guide will help you get started with this MkDocs project and understand how to work with Material for MkDocs.

Prerequisites

Before you begin, make sure you have the following installed:

  • Python 3.8 or higher
  • pip (Python package installer)

Installation

1. Install Dependencies

Install MkDocs and the Material theme using pip:

pip install -r requirements.txt

Or install them individually:

pip install mkdocs mkdocs-material

2. Preview Locally

Run the built-in development server to preview your documentation:

mkdocs serve

This will start a local server at http://127.0.0.1:8000/. The server will automatically reload when you make changes to your documentation.

3. Build the Site

To build the static site:

mkdocs build

This generates a site/ directory containing the static HTML files ready for deployment.

Project Structure

The project is organized as follows:

.
├── mkdocs.yml          # Configuration file
├── docs/               # Documentation source files
│   ├── index.md       # Home page
│   ├── getting-started.md
│   ├── about.md
│   └── deployment/
│       ├── cloudflare-pages.md
│       └── configuration.md
└── requirements.txt    # Python dependencies

Writing Documentation

Markdown Basics

MkDocs uses Markdown for documentation. Here are some common elements:

Headers

# H1 Header
## H2 Header
### H3 Header

Lists

Unordered lists:

  • Item 1
  • Item 2
  • Nested item
  • Another nested item

Ordered lists:

  1. First item
  2. Second item
  3. Third item
[Link text](https://example.com)
![Image alt text](path/to/image.png)

Code Blocks

Use triple backticks with a language identifier for syntax highlighting:

def example():
    return "Hello, World!"

Admonitions

Create highlighted boxes for notes, warnings, and tips:

!!! note "Optional Title"
    This is a note with custom title.

!!! warning
    This is a warning without custom title.

Next Steps

Learn how to deploy to Cloudflare Pages.