IAW - Práctica MkDocs

José Juan Sánchez Hernández

IES Celia Viñas (Almería) - 2019/2020

2 Práctica: Creación de un sitio web estático con MkDocs y GitHub Pages

MkDocs es un generador de sitios web estáticos que nos permite crear de forma sencilla un sitio web para documentar un proyecto. El contenido del sitio web está escrito en texto plano en formato Markdown y se configura con un único archivo de configuración en formato YAML.

2.1 Themes para MkDocs

Los themes que se incluyen por defecto en MkDocs son:

Es posible utilizar otros themes desarrollados por otras terceras partes o desarrollar nuestro propio theme. En la wiki del proyecto MkDocs puede encontrar un listado de todos los themes que hay disponibles actualmente.

En esta práctica utilizaremos el theme Material que ha sido desarrollado por Martin Donath.

2.2 Material for MkDocs

En la web oficial de Material for MkDocs encontramos una guía de referencia sobre cómo utilizar y configurar el theme.

En esta práctica amos a utilizar una imagen Docker que contiene MkDocs y el theme Material.

2.3 Ejemplo de uso

En este ejemplo vamos a necesitar crear un proyecto que tenga la siguiente estructura de archivos.

.
└── proyecto
    ├── docs
    │   ├── about.md
    │   └── home.md
    └── mkdocs.yml

En primer lugar vamos a crear un directorio para el proyecto.

mkdir proyecto

2.3.1 Archivo de configuración mkdocs.yml

Dentro del directorio de nuestro proyecto deberemos crear el archivo de configuración YAML mkdocs.yml.

Por ejemplo, en el siguiente archivo configuración mkdocs.yml estamos indicando el nombre del sitio web que estamos creando (site_name), los enlaces a las páginas que van a aparecer en el menú de navegación (nav) y el theme que vamos a utilizar (theme).

site_name: IAW

nav:
    - Principal: index.md
    - Acerca de: about.md

theme: material

En la documentación oficial del theme Material for MkDocs puede encontrar más información sobre todas las opciones de configuración que podemos incluir en el archivo de configuración mkdocs.yml.

A continuación se muestra un ejemplo completo de todas las opciones de configuración del theme Material para el archivo mkdocs.yml.

# Project information
site_name: 'Material for MkDocs'
site_description: 'A Material Design theme for MkDocs'
site_author: 'Martin Donath'
site_url: 'https://squidfunk.github.io/mkdocs-material/'

# Repository
repo_name: 'squidfunk/mkdocs-material'
repo_url: 'https://github.com/squidfunk/mkdocs-material'

# Copyright
copyright: 'Copyright © 2016 - 2017 Martin Donath'

# Configuration
theme:
  name: 'material'
  language: 'en'
  palette:
    primary: 'indigo'
    accent: 'indigo'
  font:
    text: 'Roboto'
    code: 'Roboto Mono'

# Customization
extra:
  manifest: 'manifest.webmanifest'
  social:
    - type: 'github'
      link: 'https://github.com/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: 'linkedin'
      link: 'https://www.linkedin.com/in/squidfunk'

# Google Analytics
google_analytics:
  - 'UA-XXXXXXXX-X'
  - 'auto'

# Extensions
markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true

2.3.2 Contenido en Markdown

Los archivos con el contenido en Markdown los tenemos que crear dentro del directorio docs. En este ejemplo vamos a crear dos archivos index.md y about.md.

.
├── docs
│   ├── about.md
│   └── index.md
└── mkdocs.yml

2.3.3 Creación de un contenedor Docker con MkDocs y el theme Material

En esta práctica amos a utilizar una imagen Docker que contiene MkDocs y el theme Material.

Esta imagen nos permite:

Una vez que hemos creado la estructura del proyecto podemos empezar el desarrollo de nuestro sitio iniciando un contenedor Docker con MkDocs y el theme Material.

Nota: Vamos a crear el contenedor desde el directorio principal el proyecto porque necesitamos crear un volumen de tipo bind mount entre nuestra máquina y el contenedor Docker.

docker run --rm -it -p 8000:8000 -v "$PWD":/docs squidfunk/mkdocs-material

Una vez iniciado el contenedor podemos acceder a la URL http://localhost:8000 desde un navegador web para ver el estado actual del sitio web que estamos creando.

Ahora podemos editar nuestros archivos Markdown y ver cómo se va generando el sitio web de forma inmediata.

También es posible generar directamente el sitio web sin tener que iniciar un servidor local de desarrollo. Para generar el sitio web automáticamente podemos ejecutar el siguiente comando:

docker run --rm -it -v "$PWD":/docs squidfunk/mkdocs-material build

El comando anterior creará un directorio llamado site donde guarda el sitio web que se ha generado.

2.4 Publicar una web estática en GitHub Pages

Es posible publicar la el sitio web en GitHub Pages con el siguiente comando:

docker run --rm -it -v ~/.ssh:/root/.ssh -v "$PWD":/docs squidfunk/mkdocs-material gh-deploy

Se recomienda seguir los pasos de la documentación oficial de GitHub Pages.

3 Referencias

4 Licencia

Licencia de Creative Commons
Esta página forma parte del curso Implantación de Aplicaciones Web por José Juan Sánchez y se distribuye bajo una licencia de Creative Commons Reconocimiento-NoComercial-CompartirIgual 4.0 Internacional.