Header

This guide is designed to help you work effectively with MkDocs and the Material theme on the ETH Zurich VM. It contains instructions for setting up the system, organising your project, configuring files, building your site and streamlining your documentation workflow with practical examples.

Last Updated: October 17, 2025 (JCW)

System Overview

Operating System

Rocky Linux 9.6 (Blue Onyx)

Check version:

cat /etc/redhat-release

Network Configuration

Property Value
Hostname gdc-ht.ethz.ch (gdc-docs.ethz.ch)
IPv4 Address 129.132.216.67
IPv6 Address 2001:67c:10ec:5ac1::3fc

Verify with:

hostname              # Display hostname
hostname -I           # Display IP addresses

Access Information

DNS Aliases

The VM is accessible via multiple DNS names (all resolve to the same server):

These aliases can be used interchangeably within the ETH Zurich network.

Site URL Structure

Each MkDocs site follows this URL pattern:

https://gdc-docs.ethz.ch/<PROJECT_NAME>/site/
Example:
https://www.gdc-docs.ethz.ch/FirstAidAmpSeq/site/

MkDocs Configuration

Version Information

MkDocs Version: 1.5.3

Check version:

mkdocs -V

Building Documentation

To build your documentation site:

/usr/local/bin/mkdocs -v build

Alias: sm

Project Structure

Essential Folders

Every MkDocs project requires the following directory structure:

project-root/
├── docs/ # Markdown source files
├── site/ # Generated static site (after build)
├── images/ # Image assets
└── mkdocs.yml # Configuration file

Working with Images

Reference images in your markdown files:

![Description](images/filename.png)

Or with HTML for more control:

<img src="images/filename.png" alt="Description" width="500">

Configuration Template

Complete mkdocs.yml Template (v1.5.x)

# Project information
site_name: '<Your Site Title>'
site_description: 'Support Site'
site_author: '<Author Name(s)>'
site_url: '<Full URL>'

# Documentation layout
nav:
  - 'Start': 'index.md'
  - 'Acknowledgement': 'acknowledgement.md'

# Copyright
copyright: 'Copyright &copy; 2025 XYZ'

# Configuration
theme:
  name: material
  highlightjs: true
  features:
    - navigation.sections
    - navigation.expand
    - header.autohide
    - content.code.copy
  palette:
    - scheme: default
      primary: teal
      accent: teal
      toggle:
        icon: material/lightbulb
        name: Switch to dark mode
    - scheme: slate
      primary: teal
      accent: teal
      toggle:
        icon: material/lightbulb-outline
        name: Switch to light mode
  font:
    text: Roboto
    code: Roboto Mono
  language: en
  icon:
    logo: material/library

plugins:
  - search

markdown_extensions:
  - tables
  - attr_list
  - md_in_html
  - admonition
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.details
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.keys
  - pymdownx.betterem
  - pymdownx.highlight
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.arithmatex
  - pymdownx.escapeall
  - pymdownx.smartsymbols
  - pymdownx.tasklist:
      custom_checkbox: true
      clickable_checkbox: true

extra_javascript:
  - js/extra.js
  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML
  - mathjaxhelper.js

Tips and Tricks

Collapsible Code Blocks

Create expandable sections with code:

<details>
<summary>Click to view solution</summary>
<p>
<pre><code>
echo "=== Save My History ===" >  MyHistory.txt
echo "${USER}"                 >> MyHistory.txt
echo "-----------------------" >> MyHistory.txt
history | tail -n 20           >> MyHistory.txt
echo "-----------------------" >> MyHistory.txt
date "+%A, %d.%B %Y"           >> MyHistory.txt
clear; cat MyHistory.txt
</code></pre>
</p>
</details>

Image Captions

Add professional captions to images:

<figure class="inline end" markdown>
  ![Descriptive alt text](https://www.gdc-docs.ethz.ch/.../mic.png){ width="200" align=left }
  <figcaption>Your caption text here</figcaption>
</figure>

Flowcharts with Mermaid

Create diagrams directly in markdown:

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B -->|No| E[Yay!];
```

Text Formatting

Subscripts and Superscripts:

  • Water molecule: H~2~O → H₂O
  • Exponential: N^E^ → Nᴱ

Keyboard Keys:

  • Delete: ++ctrl+alt+del++
  • Copy: ++ctrl+c++

Text Highlighting:

  • Mark: ==highlighted text==
  • Strikethrough: ~~deleted text~~
  • Insert: ^^inserted text^^

Additional Resources

Official Documentation

Extensions and Features