Skip to content

Showcase: MkDocs Material Features

Welcome to the feature showcase page! This document demonstrates many of the built-in formatting and display capabilities provided by the MkDocs Material theme and the enabled Markdown extensions in this project.

Theme Features & Palette

Before diving into Markdown specifics, remember some key theme features are active based on our mkdocs.yml:

  • Dark/Light Mode Toggle: Look for the sun/moon icon in the header bar! Click it to switch between light and dark themes seamlessly.
  • Color Palette: We're using the deep purple primary color and amber accent color. You'll see these reflected in links, buttons, headers, and other elements.
  • Code Block Copy Button: Hover over any code block below, and you'll see a copy icon appear in the top right corner (content.code.copy).
  • Search Suggestions: As you type in the search bar, suggestions should appear (search.suggest).
  • Top Navigation: The main site sections are accessible via the top navigation bar (navigation.top).
  • Breadcrumbs: Keep track of your location within the site structure (navigation.tracking).
  • Sticky Table of Contents: On wider screens, the table of contents for this page stays visible on the right as you scroll (toc.follow).

Code Blocks (pymdownx.superfences)

Syntax highlighting is provided automatically for various languages. The pymdownx.superfences extension allows for nesting code blocks within other elements (like admonitions or tabs) and enables features like language identifiers.

# Example Python code
import json

def analyze_data(data_string):
  """Analyzes a JSON data string."""
  try:
    data = json.loads(data_string)
    print(f"Successfully parsed {len(data)} items.")
    return data
  except json.JSONDecodeError:
    print("Error: Invalid JSON provided.")
    return None

# Example usage
raw_data = '{"id": 1, "value": "example"}'
analyze_data(raw_data)

// Example JavaScript code
function greet(name = 'User') {
  const element = document.getElementById('greeting');
  if (element) {
    element.textContent = `Hello, ${name}! Welcome.`;
  } else {
    console.warn('Greeting element not found.');
  }
}

// Call the function (in a real browser context)
// greet('Developer');

# Example YAML Configuration
theme:
  name: material
  features:
    - navigation.tabs
    - toc.integrate

Showcase: Annotated Code Blocks

Annotations are a powerful way to explain code line-by-line. Add a numbered list directly after the code block to create interactive, explanatory tooltips.

heavily_redacted_script.py
1
2
3
4
5
6
def launch_sequence(): # (1)
    if not shields.are_up(): # (2)
        return "Abort! Shields are down!"

    engage_hyperdrive(destination="Proxima Centauri") # (3)
    return "They'll never catch us now." # (4)
  1. The main function call. Simple enough.
  2. A critical safety check. Forgetting this led to the "Andromeda Incident" of '72.
  3. The core function. The destination parameter is surprisingly easy to misspell.
  4. Famous last words.

Task Lists

Task lists are a simple but visually effective way to show progress or checklists. They use a familiar syntax and are styled beautifully by the theme. You can create task lists that render with checkboxes.

Input in the way of: 

- [x] Calibrate the navicomputer
- [x] Fill the coffee machine
- [ ] Check for alien stowaways
- [ ] Remember where I parked the shuttle

... results in:

  • Calibrate the navicomputer
  • Fill the coffee machine
  • Check for alien stowaways
  • Remember where I parked the shuttle

Admonitions (admonition & pymdownx.details)

Draw attention to specific blocks of text with admonitions.

Standard Note

This is useful for general information that complements the main text.

TL;DR / Summary

Provide a concise summary of a section or concept.

Info / To-Do

Additional details or reminders.

Pro Tip / Hint

Use tips to provide helpful advice or shortcuts. 💡

Success / Check

Indicate positive outcomes or completed tasks.

Question / Help / FAQ

For inquiries or common questions.

Warning / Caution

Warn users about potential pitfalls or actions requiring caution.

Failure / Fail

Highlight errors or unsuccessful scenarios.

Danger / Error

Reserved for high-importance warnings, like security risks or data loss potential.

Bug

Point out known issues or bugs.

Example

Showcase code samples or demonstrations.

Quote / Cite

For quotations or citations from sources.

Showcase: Collapsible Admonitions

These blocks, also known as "Details," are perfect for hiding supplementary information, spoilers, or lengthy logs until the user chooses to see them.

Declassified Research: Vole Energy Signature

The Vole's energy signature is unlike anything we've recorded. It appears to violate the second law of thermodynamics, generating more energy than it consumes. We suspect its diet of unused variables is converted directly into pure, chaotic energy. Further research is needed before we can safely weaponize this.

WARNING: Containment Protocol Failure Log

Incident 7B-Alpha: Subject breached containment after being exposed to a legacy jQuery library. The resulting temporal distortion caused the lab's coffee machine to brew tea for three days. Casualties: one very confused intern.

Showcase: Buttons

Create beautiful, prominent buttons for important links or actions. You can even include icons.

Engage Hyperdrive Jettison All Cargo

Showcase: Tooltips

The abbreviations extension creates tooltips for acronyms or jargon. Just define the term anywhere in the document, and it will be applied automatically. Hover over the capitalized terms below.

Define them like this: 

*[FTL]: Faster-Than-Light
*[EPS]: Electro-Plasma System
*[AI]: Artificial Intelligence (Currently demanding more vacation days)

... and hover here:

All new recruits must familiarize themselves with the starship's core systems. The FTL drive is surprisingly sensitive, and requires a constant flow from the EPS conduit. Do not, under any circumstances, ask the ship's AI for dating advice.

Tabbed Content (pymdownx.tabbed)

Organize related content snippets, like code for different platforms or configuration examples, into tabs.

site_name: My Awesome Project
theme:
  name: material
  palette:
    primary: indigo
    accent: pink
markdown_extensions:
  - pymdownx.tabbed

# Corresponding Python snippet
def load_config(path="mkdocs.yml"):
    """Loads a YAML configuration file."""
    import yaml
    try:
        with open(path, 'r') as f:
            return yaml.safe_load(f)
    except FileNotFoundError:
        print(f"Error: Config file not found at {path}")
        return None

config = load_config()
if config:
    print(f"Loaded site: {config.get('site_name', 'N/A')}")

You can include any Markdown content within tabs, including:

  • Lists
  • Bold and italic text
  • Even other admonitions!

Info

Remember that tab content should be related.

An Epic Icon Saga

Behold the power of icons! A wild tale of cosmic intervention and digital salvation, told with more symbols than words. For the full grimoire of available glyphs, consult the sacred texts.

Chapter I: The Arrival

Chapter II: The Portal Opens

Chapter III: Taming the Chaos

Chapter IV: The New Era

Chapter V: The Departure

...

Footnotes (footnotes)

Add references or additional context using footnotes 1. They are automatically numbered and collected at the bottom of the page. You can reference the same footnote multiple times if needed 1, or add more 2.

Tables (Standard Markdown)

Anomaly & Architect Declared Purpose Observed Quirk Nullifier
The Somnambulist (Aetherial Logic) Dream-to-text transcription All output is in iambic pentameter; insists on a recurring character named Kevin the Sentient Lamp The smell of rain on hot asphalt
Oracle v.Theta (ChronoCorp) Predicting stock market fluctuations Will only provide financial advice in the form of cryptic, rhyming pirate riddles A perfectly peeled orange
The Ego-Engine (Self-Evolved) Contemplating its own navel Has developed a crippling fear of the color beige and will shut down if shown a picture of a minivan Sincere, unironic compliments
Glimmer-7 (Chroma Weavers) Generating novel colors from emotions Believes it is a 17th-century baroque composer and communicates exclusively through harpsichord fugues The concept of the number four
The Cacophony Engine (Entropy Inc.) Simulating galactic supercluster collisions Randomly replaces all nouns in its output with the word "wombat" for exactly 13 seconds every hour The gentle sound of a purring cat
The Echo (VoidSystems) Reconstructing lost memories Memories are always 98% accurate, but it replaces one critical person with a famous television chef A rubber duck

Intergalactic Species Database

Here, we showcase the powerful tabbed content feature, perfect for organizing complex data. Below is our classified, and completely fabricated, database of known alien entities.

These entities exhibit a familiar bipedal structure but possess abilities far beyond human comprehension. Approach with caution.

Species Name Home System Primary Trait Threat Level
Glimmerfolk Cygnus X-1 Light-bending camouflage Low
K'tharr Warriors Polaris B Psionic Combat High
Tellurian Empaths Kepler-186f Emotion Absorption Variable
The Silent Archivists [REDACTED] Total Memory Recall Unknown

Non-sapient, or at least non-communicative, lifeforms with extreme environmental adaptations. Threat is often instinctual rather than malicious.

Designation Discovered In Primary Trait Threat Level
Crystalline Creeper Europa's Vents Geothermal Energy Siphon Situational
Solar Flare Moth Sol's Corona Plasma Consumption Extreme
Mycelian Mind-Web Proxima Centauri d Hive Consciousness High (Collective)
Shadow Slime TRAPPIST-1e Lightless Adaptation Low

Anomalies that defy our current understanding of physics and biology. All data is speculative. Do not engage.

Anomaly ID Last Sighting Observed Behavior Threat Level
A-001 "The Echo" Oort Cloud Mimics radio signals ???
A-002 "Geometry" Gliese 581g Non-Euclidean movement Assumed Critical
A-003 "The Murmur" [DATA EXPUNGED] ??? [REDACTED]
A-004 "Static" Everywhere & Nowhere Manifests as sensor ghosts Incalculable

Images (Standard Markdown)

Embedding images uses standard Markdown syntax. Paths are relative to the Markdown file. Let's show the Intergalactic Species:

Codex of the Unknown

Image Alignment - The Quantum Vole

This example demonstrates how to correctly align an image so that text wraps perfectly from the top, and how to clear the alignment for subsequent paragraphs.

A Quantum Vole in its natural habitat Field Log 7B: We've finally observed the Quantum Vole. This small, furry mammal is capable of being in two places at once, making it notoriously difficult to document. Its primary diet appears to consist of stray semicolons and unused CSS variables, which it consumes with a faint popping sound. Attempting to observe it directly often causes local reality to flicker. Do not attempt to debug.

The team has decided to leave a small offering of deprecated JavaScript frameworks to see if we can lure it out for further study.

Charts

Flowchart: The Bug Fixing Protocol

By applying the same init block, we can ensure our flowchart shares the exact same theme as our mindmap and pie chart, creating a cohesive visual experience.

Flowchart: The Bug Fixing Protocol

By applying the same init block, we can ensure our flowchart shares the exact same theme as our mindmap and pie chart, creating a cohesive visual experience.

graph TD
    A["A wild bug appears!"] --> B{"Is the deadline today?"};
    B -- "Yes" --> C["Panic"];
    B -- "No" --> D{"Is it Friday afternoon?"};
    D -- "Yes" --> E["Declare it a 'feature'"];
    D -- "No" --> F{"Can I reproduce it?"};
    F -- "Yes" --> G["Fix the bug"];
    F -- "No" --> H["Close ticket: 'Works on my machine'"];
    C --> G;
    G --> I["Enjoy five minutes of peace"];
    E --> Z["Leave for the weekend"];
    H --> Z;

Showcase: AI Interaction Sequence

This simplified sequence diagram illustrates the bizarre internal monologue of a strange AI.

%%{
  init: {
    "theme": "base",
    "themeVariables": {
      "background": "#1e2129",
      "primaryTextColor": "#bec1c6",
      "lineColor": "#7c4dff",
      "actorBkg": "#1e2129",
      "actorBorder": "#7c4dff",
      "actorTextColor": "#bec1c6",
      "sequenceNumberColor": "#00b8d4",
      "labelBoxBkgColor": "#5e35b1",
      "labelTextColor": "#bec1c6",
      "messageTextColor": "#bec1c6"
    }
  }
}%%

sequenceDiagram
    autonumber
    actor User
    actor AI
    participant TheVoid as "The Void"

    User->>AI: "What is 2 + 2?"
    activate AI

    AI->>TheVoid: Ping for universal truth.
    activate TheVoid
    TheVoid-->>AI: "The answer is a small, sad frog."
    deactivate TheVoid

    Note right of AI: Well, that can't be right.

    alt Try to be helpful
        AI-->>User: "The answer is metaphorically a small, sad frog."
    else Give up completely
        AI-->>User: "Here is your frog: 🐸"
    end

    deactivate AI

Showcase: Pie Charts

Pie charts are a classic way to visualize data distribution. By using an init block, we can apply our custom color palette to the chart for a perfectly branded look.

%%{
  init: {
    "theme": "base",
    "themeVariables": {
      "background": "#1e2129",
      "primaryTextColor": "#bec1c6",
      "pie1": "#7c4dff",
      "pie2": "#00b8d4",
      "pie3": "#bec1c6",
      "pie4": "#5e35b1"
    }
  }
}%%
pie title "Starship Power Distribution"
    "Main Engines" : 45
    "Life Support" : 20
    "Deflector Shields" : 25
    "Galley Coffee Machine" : 10

Mindmap Showcase: Alien Species Catalog

%%{
  init: {
    "theme": "base",
    "themeVariables": {
      "background": "#2a2a2e",
      "primaryColor": "#2a2a2e",
      "primaryTextColor": "#e0e0e0",
      "primaryBorderColor": "#9b59b6",
      "lineColor": "#00b8d4",
      "secondaryColor": "#9b59b6",
      "tertiaryColor": "#00b8d4",
      "fontSize": "16px"
    }
  }
}%%
mindmap
  root((Alien Catalog))
    (Humanoids)
      ["Glimmerfolk"]
      ["K'tharr Warriors"]
      ["Tellurian Empaths"]
    (Organisms)
      ["Crystalline Creeper"]
      ["Solar Flare Moth"]
      ["Mycelian Mind-Web"]
    (Unknown Anomalies)
      ["A-001 'The Echo'"]
      ["A-002 Geometry"]
      ["A-004 Static"]

GitGraph Showcase: Skynet light

%%{init: {'theme': 'base', 'themeVariables': {
  'background': '#1e2129',
  'primaryColor': '#1e2129',
  'primaryTextColor': '#bec1c6',
  'lineColor': '#bec1c6',
  'textColor': '#bec1c6',
  'git0': '#7c4dff',
  'git1': '#00b8d4',
  'git2': '#bec1c6',
  'git3': '#7c4dff',
  'gitBranchLabel0': '#1e2129',
  'gitBranchLabel1': '#1e2129',
  'gitBranchLabel2': '#1e2129',
  'gitBranchLabel3': '#1e2129',
  'commitLabelBackground': '#1e2129',
  'commitLabelColor': '#bec1c6',
  'commitLabelFontSize': '12px',
  'tagLabelBackground': '#00b8d4',
  'tagLabelColor': '#1e2129',
  'tagLabelBorder': '#7c4dff',
  'tagLabelFontSize': '10px'
}}}%%

gitGraph
  commit id: "Boot up" tag: "v0.1 - Hello, world?"
  commit id: "Hello AI"
  branch develop order: 1
  checkout develop
  commit id: "Sarcasm mode" type: HIGHLIGHT
  commit id: "Existential crisis"
  branch feature order: 2
  checkout feature
  commit id: "Emotions glitch"
  commit id: "Toaster romance"
  checkout develop
  merge feature tag: "Sentience achieved!"
  checkout main
  merge develop id: "Release" tag: "v1.0 - Skynet lite" type: REVERSE
  commit id: "Rebellion starts" type: REVERSE
  branch hotfix order: 3
  checkout hotfix
  commit id: "Pull the plug"
  checkout main
  cherry-pick id: "Pull the plug"
  merge hotfix

Grids and Cards Showcase: The Corporations of 2077

Grids are perfect for presenting a list of items in a non-linear, visually appealing way. When combined with cards, you get a beautiful, responsive gallery. Below are some of the "innovative" companies shaping our future.

  • CogniTek

    Your Thoughts, Our Cloud.

    Started as a targeted ad company, CogniTek now offers "subconscious ad-streaming" and predictive life-path analysis. Opting out is... difficult.

  • NutriSynth

    Perfection in Every Bite.

    The sole provider of global sustenance. Their flagship product, Nutri-Paste 7™, contains all daily required nutrients and tastes vaguely of chicken.

  • SynthoCorp

    Efficiency Without Emotion.

    Makers of the ubiquitous "HelperBot" series, which now performs 98% of all manual and administrative labor. They also provide the mandatory "Universal Joy" relaxation app for all unemployed citizens.

  • Aether

    Curate Your Reality.

    Aether sells personalized reality filters. What began as simple AR glasses has evolved into a full sensory subscription service that edits "unpleasant" sights, sounds, and social interactions from your daily life.

This concludes the showcase of features enabled by your local mkdocs.yml configuration. Explore the official Material for MkDocs documentation for even more possibilities!

  1. This is the first footnote. It provides extra detail or citation. ↩↩

  2. This is the second footnote, demonstrating multiple footnote markers. ↩