MkDocs Authoring Guide¶

Use this guide when adding or updating pages in the Interview Handbook. The features shown here are enabled in mkdocs.yml and validated during the production build.

Create a page¶

1. Place the Markdown file in the closest subject directory.
2. Use a short lowercase kebab-case filename, such as portfolio-risk.md.
3. Start the page with one level-one heading.
4. Add the page to nav in mkdocs.yml.
5. Link related pages using relative Markdown links.
6. Run mkdocs build --strict before pushing.

Use index.md as the landing page for each directory. Keep display order and labels in mkdocs.yml rather than adding numeric prefixes to filenames.

docs/
├── index.md
├── assets/images/
├── computer-science/
│   ├── index.md
│   └── data-science/
├── statistics/
├── math/
├── commodities/
└── finance/

Page metadata¶

Front matter controls browser metadata and optional page behavior:

---
title: Portfolio Risk
description: Common portfolio risk measures and interview questions.
tags:
  - Finance
  - Risk
hide:
  - toc
---

Use a concise title and a description that makes sense in search results. Remove hide when the page benefits from the table of contents.

Navigation¶

Add new pages to nav in mkdocs.yml:

nav:
  - Finance:
      - Overview: finance/index.md
      - Risk: finance/risk.md
      - Portfolio Risk: finance/portfolio-risk.md

The configuration enables section landing pages, breadcrumbs, anchor tracking, previous/next links, a following table of contents, and a back-to-top button.

Links and assets¶

Link to Markdown source files instead of generated HTML:

[Risk](finance/risk.md)
[Data Science](computer-science/data-science/index.md)

Paths are relative to the page containing the link. From a nested page, use ../ as needed.

Store shared images under docs/assets/images/<subject>/ and always provide useful alternative text:

![Global LNG flows](assets/images/commodities/lng-flows.png)

When renaming a published page, configure a redirect or preserve its old URL so existing bookmarks do not break.

Admonitions and collapsible sections¶

Use admonitions for information that should stand apart from the main text:

!!! tip
    Compare an algorithm's time and space complexity before choosing it.

!!! warning
    Historical performance does not guarantee future returns.

??? example "Worked example"
    This explanation is collapsed until the reader opens it.

Use them selectively; too many callouts make the important ones harder to notice.

Code blocks¶

Always provide a language identifier. Optional titles and highlighted lines make examples easier to scan:

```python title="expected_value.py" hl_lines="2"
def expected_value(values, probabilities):
    return sum(value * probability for value, probability in zip(values, probabilities))
```

Line numbers can be enabled per block:

```python linenums="1"
prices = [100, 101, 99]
returns = [prices[i] / prices[i - 1] - 1 for i in range(1, len(prices))]
```

The copy button is enabled globally.

Code annotations¶

Annotations attach explanations directly to code:

```python
cache = {}  # (1)
```

1. The dictionary stores previously computed results.

Content tabs¶

Use tabs to compare languages, approaches, or platforms without repeating surrounding prose:

=== "Python"

    ```python
    values = sorted(values)
    ```

=== "SQL"

    ```sql
    SELECT * FROM values ORDER BY value;
    ```

Tabs with the same labels are synchronized across the site.

Tables and definition lists¶

Use tables when readers need to compare the same attributes:

| Measure | Captures | Limitation |
| --- | --- | --- |
| VaR | Loss threshold | Ignores losses beyond the threshold |
| Expected shortfall | Average tail loss | More data-sensitive |

Use definition lists for terminology and glossaries:

Value at Risk
:   An estimate of the potential loss over a defined period at a given confidence level.

Expected Shortfall
:   The average loss beyond the Value at Risk threshold.

Formatting and keyboard keys¶

The following additional syntax is available:

- ==Important interview point==
- H~2~O
- x^2^
- ~~Deprecated approach~~
- Press ++ctrl+c++

Use formatting to clarify meaning, not as decoration.

Task lists¶

Task lists work well for study plans and page-completion checklists:

- [x] Review probability distributions
- [ ] Practice conditional expectation
- [ ] Complete a Monte Carlo exercise

Diagrams¶

Mermaid diagrams are rendered directly from fenced text and automatically follow the light or dark color scheme:

```mermaid
flowchart LR
    Data --> Clean
    Clean --> Model
    Model --> Evaluate
```

Useful diagram types include flowcharts, sequence diagrams, state diagrams, class diagrams, and entity-relationship diagrams.

Mathematical notation¶

MathJax renders inline and block LaTeX. Use \(...\) inline:

The expected value is \(E[X]\).

Use \[...\] or $$...$$ on separate lines for display equations:

\[
\operatorname{VaR}_{\alpha}(X)
=
\inf\{x \mid P(X \leq x) \geq \alpha\}
\]

MathJax is loaded from a public CDN, so equations require network access when the site is viewed.

Footnotes and tooltips¶

Footnotes are displayed as hoverable tooltips while remaining accessible at the bottom of the page:

Expected shortfall is also known as conditional value at risk.[^1]

[^1]: Naming conventions vary across texts and regulators.

Add a tooltip to a link with its optional title:

[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/ "Theme documentation")

Abbreviations can provide short definitions:

VaR is commonly used for market-risk limits.

*[VaR]: Value at Risk

Reusable snippets¶

The snippets extension can include content from another Markdown file:

Keep reusable fragments in a clearly named directory and avoid deeply nested inclusions.

Tags¶

Tags connect pages across the folder hierarchy. Add them in front matter:

---
tags:
  - Python
  - Cheatsheet
  - Data Science
---

The generated Tags page lists tagged content. Prefer a small, consistent vocabulary rather than creating near-duplicates such as Machine Learning, ML, and machine-learning.

Search-friendly writing¶

• Give every page a unique, descriptive heading.
• Put important terminology in headings and introductory paragraphs.
• Prefer focused pages over very long collections of unrelated notes.
• Cross-link related concepts using descriptive link text.
• Add a useful description in front matter.
• Use tables for comparisons and code fences for executable examples.

Notebooks¶

Plain .ipynb files are copied as downloads; MkDocs does not render them as documentation pages. Convert important explanations into Markdown pages, or add a notebook-rendering plugin such as mkdocs-jupyter if inline notebook rendering becomes necessary. A plugin increases build time and should be added only when readers benefit from rendered outputs.

Preview and validate¶

Install dependencies and start the live preview:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Open http://127.0.0.1:8000/interview-handbook/. Saved changes to docs/ and mkdocs.yml reload automatically.

Before pushing, run the same strict production build used by GitHub Actions:

mkdocs build --strict

Warnings about missing pages and broken relative links should be resolved rather than ignored. Pages intentionally left out of navigation are reported as informational messages during the build.

Publish¶

Push to main. The workflow in .github/workflows/pages.yml builds and deploys the site. GitHub Pages must use Settings → Pages → Build and deployment → Source: GitHub Actions.