Espacio de trabajo¶

Ahora que ya sabemos que vamos a crear archivos de texto y convertirlos en páginas web, veamos las herramientas necesarias.

Editor¶

El primer paso es descargar e instalar un editor de textos, del tipo plain text, si no nos gusta el que viene de serie con nuestro sistema operativo. Para crear archivos markdown, es costumbre utilizar editores especializados en esta tarea, que muestran dos paneles, uno de edición y otro de previsualización con el aspecto final del documento:

En la elección del editor existen cientos de alternativas. Yo uso Visual Studio Code, distribuido por Microsoft de forma gratuita, con versiones para diferentes sistemas operativos. Utilizo entornos Mac y Linux, indistintamente, pero todo lo aquí descrito también es válido para Windows.

Visual Studio Code es un editor muy potente, con miles de posibilidades, que evoluciona rápidamente, y cuya descripción va más allá del propósito de este cuaderno. En todo caso, tenemos varias páginas web de interés:

Si Visual Studio Code nos parece complejo, encontraremos otras opciones en la red. Basta con hacer una búsqueda del término "editores markdown".

Conversor web¶

Tras crear los capítulos de nuestro cuaderno en forma de archivos de texto markdown, vamos a utilizar un software llamado MkDocs para generar los ficheros HTML que formarán el sitio web.

La labor que realizará MkDocs es:

tomar todos los archivos de texto markdown y generar sus correspondientes ficheros HTML.
añadir otros contenidos HTML para mostrar índices, tabla de contenido, barra de cabecera y pie de página, etc.
añadir automáticamente ficheros CSS con las reglas de estilo usadas por MkDocs
añadir scripts

Complementaremos MkDocs con otro software denominado Material for MkDocs, lo que añade capacidades de presentación y navegación.

MkDocs es un software creado en lenguaje de programación Python, y para ejecutarse, necesitamos tener el intérprete de Python en nuestro ordenador, es decir, un software capaz de entender programas Python y ejecutarlos. Por lo tanto, la secuencia de instalación es:

Instalar Python
Instalar MkDocs
Instalar Material for Mkdocs

De todas formas, la instalación de Material for Mkdocs resuelve automáticamente la de MkDocs y otros paquetes de software complementarios:

Python Markdown, que es el complemento que usa MkDocs para añadir capacidades a la sintaxis markdown
PyMdown Extensions es otro complemento para añadir más funcionalidades a markdown
Pygments es un software que permite mostrar textos en diferentes colores. Es típico cuando se trata de mostrar ejemplos de programación en un manual técnico.

Por lo tanto, el proceso completo se reduce a asegurarnos de que tenemos el intérprete de Python, y seguidamente instalar Material for Mkdocs. Este segundo paso instalará todo lo demás.

Terminal de comandos¶

MkDocs es un programa que se ejecuta desde el terminal de comandos de nuestro sistema operativo, por lo que conviene estar familiarizados con su uso básico. En Windows, se trata de un programa llamado cmd. Ver Wikipedia. En un Mac, encontraremos el programa Terminal en la carpeta Aplicaciones, apartado Utilidades.

Aunque los comandos difieren de un sistema a otro (Windows, Mac, Linux), los aquí descritos suelen ser comunes, quizás con ligeras diferencias.

Típicamente, al iniciar el Terminal se muestra un texto indicando la carpeta actual, es decir, la que se utiliza por defecto cuando en un comando no indicamos nada, seguida de un símbolo >, $, # u otro similar, denominado prompt:

C:\Users\nombreUsuario >

Este prompt nos invita a introducir un comando, que se ejecutará al pulsar Enter.

Si no estamos familiarizados con los comandos de nuestro ordenador, en la red encontraremos numerosos tutoriales sobre el tema. En este cuaderno vamos a mencionar tres comandos bastante relevantes:

para ejecutar un programa, se introduce su nombre. Por ejemplo, para iniciar el editor de texto bloc de notas en Windows:
```
> notepad
```
Típicamente, los comandos pueden ir acompañados de "argumentos". Por ejemplo, para iniciar el editor con un archivo abierto para su edición:
```
> notepad miarchivo.txt
```
para conocer cual es el directorio actual usar el comando cd en Windows o pwd en Mac/Linux
```
> cd
```
lo que muestra algo así como:
```
C:\Users\nombreUsuario
```
para establecer como actual otro directorio, usar el comando cd (cambiar de directorio) con el nombre de la carpeta en cuestión como argumento:
```
> cd \ruta_directorio\nombre_directorio
```
En las plataformas Mac/Linux se usa la barra / en lugar de la invertida \, que es típica de Windows:
```
$ cd /ruta_directorio/nombre_directorio
```

Python¶

La instalación del intérprete de lenguaje Python es el primer requisito a cumplir. Podemos comprobar que ya lo tenemos abriendo el terminal de comandos y ejecutando:

$ python -V

O bien, dependiendo de nuestra máquina:

$ python3 -V

lo que nos debería indicar la versión de Python que hay en nuestro equipo:

$ python3 -V
Python 3.12.4

¡Atención! El argumento -V se escribe en mayúsculas.

Python 3

Python es un lenguaje de programación que ha ido evolucionando con el paso de los años. La versión más reciente es Python 3, por lo que en algunas instalaciones, es posible que el comando a ejecutar sea pyton3 en lugar de python

Si no tenemos el intérprete de Python, hay que instalarlo siguiendo las instrucciones de la página web oficial. Típicamente, podemos hacerlo a partir de la Microsoft Store (Windows), descargando el programa instalador de la página web oficial (Windows/Mac) o acudiendo al repositorio de nuestra distribución Linux.

Instalar Material for MkDocs¶

Una vez que contamos con el intérprete de Python en nuestro ordenador, podemos instalar y ejecutar programas escritos en Python. MkDocs y todos los complementos utilizados se instalan com el comando pip (package installer for Python), un pequeño programa que acompaña al intérprete de Python. Comprobamos su existencia abriendo el terminal de comandos y tecleando:

$ pip --version

O bien con:

$ pip3 --version

Obtenemos la lista de paquetes de software Python instalados en nuestro equipo con el comando:

$ pip3 list

La instalación de Material for MkDocs incluye automáticamente el resto de módulos: MkDocs, Python Markdown, PyMdown Extensions y Pygments. Basta con ejecutar el comando:

$ pip3 install mkdocs-material

Dependiendo del sistema operativo, es posible que haya que hacer la instalación con permisos de administrador.

Actualizar Material for MkDocs¶

Podemos comprobar cual es la versión actual de Material for MkDocs con el comando:

$ pip3 show mkdocs-material

Para actualizar a una nueva versión, ejecutamos:

$ pip3 install --upgrade --force-reinstall mkdocs-material

Podemos comprobar las novedades de cada versión en la página web de Material for MkDocs.

La actualización de Material for MkDocs comprueba automáticamente el resto de módulos mencionados MkDocs, Python Markdown, PyMdown Extensions y Pygments, actualizándolos si es necesario.