1 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.

1.1 Themes para MkDocs

Los themes que se incluyen por defecto en MkDocs son:

• mkdocs
• readthedocs

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.

1.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.

1.3 Uso de un contenedor Docker con MkDocs y el theme Material

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

Esta imagen Docker nos permite:

• Crear un nuevo proyecto (Comando: new).
• Crear un servidor de desarrollo local (Comando: serve).
• Generar la documentación (Comando: build).
• Publicar la documentación en GitHub Pages (Comando: gh-deploy).

A continuación, se muestran las opciones y los comandos que se pueden utilizar con la imagen Docker squidfunk/mkdocs-material.

Usage: mkdocs [OPTIONS] COMMAND [ARGS]...

  MkDocs - Project documentation with Markdown.

Options:
  -V, --version  Show the version and exit.
  -q, --quiet    Silence warnings
  -v, --verbose  Enable verbose output
  -h, --help     Show this message and exit.

Commands:
  build      Build the MkDocs documentation
  gh-deploy  Deploy your documentation to GitHub Pages
  new        Create a new MkDocs project
  serve      Run the builtin development server

1.3.1 Crear un nuevo proyecto (Comando: new)

En primer lugar vamos a situarnos en el directorio donde queremos crear nuestro proyecto. En nuestro caso será el directorio proyecto.

Para crear la estructura de archivos del proyecto MkDocs podemos hacer uso del comando new, como se muestra en el siguiente ejemplo.

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

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.

El comando anterior creará el archivo de configuración mkdocs.yml y el archivo Markdown index.md dentro del directorio docs.

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

1.3.2 Contenido en Markdown

Todos los archivos con el contenido en Markdown tienen que estar dentro del directorio docs. Por ejemplo, vamos a crear un nuevo archivo about.md de modo que nuestro proyecto quedará con la siguiente estructura de archivos.

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

1.3.3 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.

1.3.4 Crear un servidor de desarrollo local (Comando: serve)

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.

1.3.5 Personalización del theme Material

A continuación, se enumeran todas las opciones de configuración que podemos realizar sobre el theme Material.

• Cambiar el color.
• Cambiar la fuente de letra.
• Cambiar el idioma.
• Cambiar el logo y los iconos.
• Configurar la navegación.
• Configurar las búsquedas.
• Configurar Google Analytics.
• Configurar el versionado de la documentación.
• Configurar la cabecera.
• Configurar el pie de página.
• Añadir un repositorio de git.
• Añadir Disqus.

1.3.6 Generar la documentación (Comando: build)

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.

1.3.7 Publicar la documentación en GitHub Pages (Comando: gh-deploy)

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.

1.4 Creación de un workflow de CI/CD en GitHub Actions para pubicar un sitio web en GitHub Pages

En esta sección vamos a ver cómo podemos configurar un workflow en GitHub Actions para publicar el sitio web que hemos creado en GitHub Actions.

Para crear un workflow en GitHub Actions podemos hacerlo de dos formas:

1. Desde la sección Actions -> New workflow.
2. Creando un archivo YAML dentro del directorio .github/workflows, en nuestro repositorio.

En nuestro caso, vamos a crear un archivo con el nombre build-push-mkdocs.yaml. Por lo tanto, nuestro repositorio quedará así:

.
├── .github
│   └── workflows
│   │   └── build-push-mkdocs.yaml
└── proyecto
    ├── docs
    │   └── index.md
    └── mkdocs.yml

El workflow que vamos a diseñar se va a ejecutar después de que se realice una operación de push sobre la rama main del repositorio, y las acciones que realizará son:

• Clonar la rama main del repositorio.
• Instalar python3.
• Instalar mkdocs y el theme mkdocs-material.
• Ejecutar el comando mkdocs build dentro del repositorio para generar el sitio web en HTML.
• Publicar el sitio web en la rama gh-pages de nuestro repositorio.

Después de que se ejecute el workflow, en nuestro repositorio tendremos dos ramas, la rama main con el código Markdown de nuestro sitio y la rama gh-pages donde estará nuestro sitio web en HTML.

El contenido del archivo build-push-mkdocs.yaml es el siguiente.

name: build-push-mkdocs

# Eventos que desescandenan el workflow
on:
  push:
    branches: ["main"]

  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:

  # Job para crear la documentación de mkdocs
  build:
    # Indicamos que este job se ejecutará en una máquina virtual con la última versión de ubuntu
    runs-on: ubuntu-latest
    
    # Definimos los pasos de este job
    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      - name: Install Python3
        uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: Install Mkdocs
        run: |
          pip install mkdocs
          pip install mkdocs-material 

      - name: Build MkDocs
        run: |
          mkdocs build

      - name: Push the documentation in a branch
        uses: s0/git-publish-subdir-action@develop
        env:
          REPO: self
          BRANCH: gh-pages # The branch name where you want to push the assets
          FOLDER: site # The directory where your assets are generated
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub will automatically add this - you don't need to bother getting a token
          MESSAGE: "Build: ({sha}) {msg}" # The commit message

El último paso que tendremos que realizar será configurar los permisos que tendrá el GITHUB_TOKEN cuando se ejecute el workflow en este repositorio.

Para configurar el repositorio seleccionamos: Settings -> Actions -> General.

Buscamos la sección Workflow permissions y seleccionamos la opción Read and write permissions.

2 Referencias

• MkDocs
• Markdown
• YAML

3 Licencia

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