Skip to content

MkDocs

We are using MkDocs to generate our documentation. See Docker-mkdocs repo for information about MkDocs and the image we're using.

Work on docs locally

The first time starting the container may take longer due to downloading the ~40MB docker image

  1. Run the mkdocs container.

    docker-compose up mkdocs # (1)!
    1. Optionally use the -d flag to run the container in the background

  2. Open a browser to http://localhost:8005/ to view the documentation locally.

  3. Modify the files in the docs directory. The site will auto-update when the files are saved.

  4. Ctrl+C to quit the local server and stop the container

Auto-generated docs

We have a GitHub Action set up to generate and host the documentation on a GitHub Pages site

MkDocs syntax

We're using Material for MkDocs. Aside from standard markdown syntax, there are some MkDocs and Material-specific syntax which can help more effective documentation. See the Material reference docs for the complete set of syntax.

Here's a list of commonly used MkDocs syntax for quick reference.

Code Blocks

Code Block
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
    list_display = (
        "name",
        "start_time",
        "duration_in_min",
    )
Numbered Lines
1
2
3
4
5
6
7
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
    list_display = (
        "name",
        "start_time",
        "duration_in_min",
    )
Highlighted Lines
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
    list_display = (
        "name",
        "start_time",
        "duration_in_min",
    )

```python title="Code Block"
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
    list_display = (
        "name",
        "start_time",
        "duration_in_min",
    )
```

```python title="Numbered Lines" linenums="1"
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
    list_display = (
        "name",
        "start_time",
        "duration_in_min",
    )
```

```python title="Highlighted Lines" hl_lines="1 3 5"
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
    list_display = (
        "name",
        "start_time",
        "duration_in_min",
    )
```

Code Annotations

Click the plus sign --> # (1)!
  1. This is an explanation text
``` bash
Click the plus sign --> # (1)!
```

1. This is an explanation text

Text blocks

Simple Block

Example

Content Block Text

Expandable Block

Content

Opened Expandable Block

Content

!!! example "Simple Block"

!!! example
    Content Block Text

??? example "Expandable Block"
    Content

???+ example "Opened Expandable Block"
    Content

Tabbed content

linux-specific content

mac-specific content

=== "Linux"

    linux-specific content

=== "Mac"

    mac-specific content

Buttons

  1. Ctrl+C to quit the local server and stop the container
1. ++ctrl+c++ to quit the local server and stop the container