MkDocs Cheatsheet

MkDocs - Documentación del proyecto con Markdown

__HTML_TAG_94_ MkDocs es un generador de sitio estático rápido, sencillo y vertical que está diseñado para construir la documentación del proyecto. Los archivos fuente de documentación están escritos en Markdown y configurados con un solo archivo de configuración YAML.

Tabla de contenidos¶

Instalación
[Empezar] (Pruébalo)
[Estructura de proyecto]
Configuración
[Documentación de escritura] (documentación de escritura)
[Navigation] (#navigation)
[Temas]
Plugins
Extensiones
Deployment
[Temas del átomo] (Temas del fondo)
Configuración avanzada
[Internacionalización] (#internacionalización)
Buscar
API Documentation
Performance
[Prácticas mejores] (prácticas mejores)

Instalación¶

Instalación de pitón¶

# Install Python (if not already installed)
# MkDocs requires Python 3.7+

# Check Python version
python --version
python3 --version

Install MkDocs¶

# Install via pip
pip install mkdocs

# Install with additional dependencies
pip install mkdocs[i18n]

# Install specific version
pip install mkdocs==1.5.3

# Verify installation
mkdocs --version

Virtual Environment (Recommended)¶

# Create virtual environment
python -m venv mkdocs-env

# Activate virtual environment
# On Windows
mkdocs-env\Scripts\activate
# On macOS/Linux
source mkdocs-env/bin/activate

# Install MkDocs
pip install mkdocs

# Deactivate when done
deactivate

Development Instalación¶

# Install from source
git clone https://github.com/mkdocs/mkdocs.git
cd mkdocs
pip install -e .

# Install development dependencies
pip install -r requirements/dev.txt

Get Started¶

Create New Project¶

# Create new MkDocs project
mkdocs new my-project

# Navigate to project directory
cd my-project

# Project structure created:
# my-project/
#   ├── docs/
#   │   └── index.md
#   └── mkdocs.yml

Basic Commands¶

# Start development server
mkdocs serve

# Start on custom port
mkdocs serve --dev-addr=127.0.0.1:8080

# Build static site
mkdocs build

# Build and clean output directory
mkdocs build --clean

# Deploy to GitHub Pages
mkdocs gh-deploy

First Documentation¶

<!-- docs/index.md -->
# Welcome to My Project

This is the homepage of my documentation.

## Features

- Easy to use
- Fast and responsive
- Beautiful themes

## Getting Started

Check out the [User Guide](user-guide.md) to get started.

# mkdocs.yml
site_name: My Project Documentation
site_description: A comprehensive guide to my project
site_author: Your Name
site_url: https://yourname.github.io/my-project

nav:
  - Home: index.md
  - User Guide: user-guide.md
  - API Reference: api.md

theme:
  name: material

Project Structure¶

Basic Structure¶

my-project/
├── docs/                 # Documentation source files
│   ├── index.md         # Homepage
│   ├── user-guide.md    # User guide
│   ├── api.md           # API documentation
│   ├── images/          # Images and assets
│   └── stylesheets/     # Custom CSS
├── mkdocs.yml           # Configuration file
└── site/                # Generated site (after build)

Advanced Structure¶

my-project/
├── docs/
│   ├── index.md
│   ├── getting-started/
│   │   ├── index.md
│   │   ├── installation.md
│   │   └── quickstart.md
│   ├── user-guide/
│   │   ├── index.md
│   │   ├── configuration.md
│   │   └── advanced.md
│   ├── api/
│   │   ├── index.md
│   │   ├── endpoints.md
│   │   └── examples.md
│   ├── assets/
│   │   ├── images/
│   │   ├── css/
│   │   └── js/
│   └── overrides/        # Theme overrides
├── mkdocs.yml
├── requirements.txt      # Python dependencies
└── .github/
    └── workflows/
        └── ci.yml        # GitHub Actions

Multi-language Structure¶

my-project/
├── docs/
│   ├── en/              # English documentation
│   │   ├── index.md
│   │   └── guide.md
│   ├── es/              # Spanish documentation
│   │   ├── index.md
│   │   └── guide.md
│   └── fr/              # French documentation
│       ├── index.md
│       └── guide.md
├── mkdocs.yml
├── mkdocs.es.yml        # Spanish config
└── mkdocs.fr.yml        # French config

Configuración¶

Configuración básica¶

# mkdocs.yml
site_name: My Project
site_description: A great project
site_author: Your Name
site_url: https://example.com

# Repository
repo_name: username/repository
repo_url: https://github.com/username/repository
edit_uri: edit/main/docs/

# Copyright
copyright: Copyright &copy; 2023 Your Name

# Navigation
nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quickstart.md
  - User Guide:
    - Overview: user-guide/index.md
    - Configuration: user-guide/configuration.md
  - API Reference: api.md

# Theme
theme:
  name: material
  language: en

# Build
docs_dir: docs
site_dir: site

Configuración avanzada¶

# mkdocs.yml
site_name: Advanced Project Documentation
site_description: Comprehensive documentation with advanced features
site_author: Your Name
site_url: https://docs.example.com

# Repository information
repo_name: username/project
repo_url: https://github.com/username/project
edit_uri: edit/main/docs/

# Copyright and legal
copyright: |
  Copyright &copy; 2023 <a href="https://example.com">Your Company</a><br>
  Licensed under <a href="https://opensource.org/licenses/MIT">MIT License</a>

# Navigation structure
nav:
  - Home: index.md
  - Getting Started:
    - Overview: getting-started/index.md
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quickstart.md
    - Configuration: getting-started/configuration.md
  - User Guide:
    - Introduction: user-guide/index.md
    - Basic Usage: user-guide/basic-usage.md
    - Advanced Features: user-guide/advanced.md
    - Troubleshooting: user-guide/troubleshooting.md
  - API Reference:
    - Overview: api/index.md
    - Authentication: api/auth.md
    - Endpoints: api/endpoints.md
    - Examples: api/examples.md
  - Development:
    - Contributing: development/contributing.md
    - Testing: development/testing.md
    - Release Notes: development/changelog.md

# Theme configuration
theme:
  name: material
  language: en
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.highlight
    - search.share
    - content.code.copy

# Plugins
plugins:
  - search:
      lang: en
  - minify:
      minify_html: true
  - git-revision-date-localized:
      type: date

# Markdown extensions
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.tabbed:
      alternate_style: true
  - attr_list
  - md_in_html
  - tables
  - footnotes
  - toc:
      permalink: true

# Extra CSS and JavaScript
extra_css:
  - stylesheets/extra.css
  - stylesheets/custom.css

extra_javascript:
  - javascripts/extra.js
  - https://unpkg.com/mermaid@8.6.4/dist/mermaid.min.js

# Extra configuration
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/username
  analytics:
    provider: google
    property: G-XXXXXXXXXX
  version:
    provider: mike

Environment-specific Configuración¶

# mkdocs.yml (base configuration)
site_name: My Project
docs_dir: docs
site_dir: site

# Development configuration
dev_addr: 127.0.0.1:8000
use_directory_urls: true

# Production configuration
site_url: https://docs.example.com
use_directory_urls: false

Escritura Documentación¶

Markdown Basics¶

# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`

- Unordered list item 1
- Unordered list item 2
  - Nested item

1. Ordered list item 1
2. Ordered list item 2

[Link text](https://example.com)
[Internal link](user-guide.md)
[Link with title](https://example.com "Title")

![Image alt text](images/screenshot.png)
![Image with title](images/diagram.png "Diagram Title")

Code Blocks¶

`markdownpython def hello_world(): print("Hola, Mundo!") ```

```_python title="example.py" def salud(nombre): ¡Hola!

print(greet("MkDocs") ```

``python linenums="1" def fibonacci(n): <= 1: return n return fibonacci(n-1) + fibonacci(n-2) __CODE_BLOCK_18__python hl_lines="2 3" def process_data(data): cleaned_data = clean(data) # This line is highlighted result = analyze(cleaned_data) # This line is highlighted return result __CODE_BLOCK_19__

Tables¶

CODE_BLOCK_20

Admonitions¶

CODE_BLOCK_21

Content Tabs¶

CODE_BLOCK_22__python def hello(): print("Hello from Python!") __CODE_BLOCK_23__javascript function hello() { console.log("Hello from JavaScript!"); } __CODE_BLOCK_24__bash echo "Hello from Bash!" __CODE_BLOCK_25

Footnotes¶

CODE_BLOCK_26

CODE_BLOCK_27

CODE_BLOCK_28

CODE_BLOCK_29

CODE_BLOCK_30

CODE_BLOCK_31

Themes¶

Material Theme¶

CODE_BLOCK_32

CODE_BLOCK_33

ReadTheDocs Theme¶

CODE_BLOCK_34

Custom Theme Configuration¶

CODE_BLOCK_35

Theme Switching¶

CODE_BLOCK_36

Plugins¶

Essential Plugins¶

CODE_BLOCK_37

Search Plugin¶

CODE_BLOCK_38

Git Revision Date Plugin¶

CODE_BLOCK_39

Minify Plugin¶

CODE_BLOCK_40

Awesome Pages Plugin¶

CODE_BLOCK_41

Redirects Plugin¶

CODE_BLOCK_42

Custom Plugin Configuration¶

CODE_BLOCK_43

Extensions¶

PyMdown Extensions¶

CODE_BLOCK_44

CODE_BLOCK_45

Code Highlighting¶

CODE_BLOCK_46

Math Support¶

CODE_BLOCK_47

CODE_BLOCK_48

Deployment¶

GitHub Pages¶

CODE_BLOCK_49

GitHub Actions¶

CODE_BLOCK_50

Netlify¶

CODE_BLOCK_51

Vercel¶

CODE_BLOCK_52

Docker Deployment¶

CODE_BLOCK_53

CODE_BLOCK_54

Custom Domain¶

CODE_BLOCK_55

CODE_BLOCK_56

Custom Themes¶

Theme Structure¶

CODE_BLOCK_57

Base Template¶

CODE_BLOCK_58

Content Template¶

CODE_BLOCK_59

CODE_BLOCK_60

Advanced Configuration¶

Multi-site Configuration¶

CODE_BLOCK_61

Environment Variables¶

CODE_BLOCK_62

Conditional Configuration¶

CODE_BLOCK_63

Custom Hooks¶

CODE_BLOCK_64

CODE_BLOCK_65

Internationalization¶

Multi-language Setup¶

CODE_BLOCK_66

Language-specific Content¶

CODE_BLOCK_67

Translation Structure¶

CODE_BLOCK_68

Search¶

Local Search Configuration¶

CODE_BLOCK_69

External Search Integration¶

CODE_BLOCK_70

CODE_BLOCK_71

Custom Search¶

CODE_BLOCK_72

API Documentation¶

Auto-generated API Docs¶

CODE_BLOCK_73

CODE_BLOCK_74

CODE_BLOCK_75

OpenAPI Integration¶

CODE_BLOCK_76

CODE_BLOCK_77

CODE_BLOCK_78

Manual API Documentation¶

CODE_BLOCK_79__http GET /api/v1/users Authorization: Bearer YOUR_API_KEY __CODE_BLOCK_80__json { "users": [ { "id": 1, "name": "John Doe", "email": "john@example.com" } ], "total": 100, "limit": 10, "offset": 0 } __CODE_BLOCK_81__bash curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.example.com/v1/users?limit=5" __CODE_BLOCK_82

Performance¶

Build Optimization¶

CODE_BLOCK_83

Caching Strategy¶

CODE_BLOCK_84

Image Optimization¶

CODE_BLOCK_85

CODE_BLOCK_86

Lazy Loading¶

CODE_BLOCK_87

Best Practices¶

Content Organization¶

CODE_BLOCK_88

Writing Best Practices¶

Use clear headings for better navigation
Include code examples with proper syntax highlighting
Add screenshots for visual guidance
Write concise descriptions for better understanding
Use consistent formatting across all pages
Include cross-references between related topics

SEO Optimization¶

CODE_BLOCK_89

Maintenance Best Practices¶

Regular updates to keep content current
Link checking to prevent broken links
Performance monitoring for build times
User feedback integration for improvements
Version control for documentation changes
Automated testing for documentation builds

Summary¶

MkDocs is a powerful static site generator specifically designed for project documentation. Key features include:

Markdown-based: Write documentation in simple Markdown
Python-powered: Extensible with Python plugins
Theme support: Beautiful themes including Material Design
Live preview: Real-time preview during development
Easy deployment: Simple deployment to various platforms
Plugin ecosystem: Rich ecosystem of plugins for extended functionality
Search integration: Built-in search with external search support
Multi-language: Support for internationalization

By following best practices and leveraging MkDocs' capabilities, you can create professional, maintainable documentation that serves your users effectively and grows with your project.