Texto fuente¶

Llamamos texto fuente a los fragmentos de programación que encontramos en los manuales técnicos. Por ejemplo, supongamos el siguiente programa escrito en lenguaje Java:

class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }

Nótese la capacidad que tiene MkDocs para colorear los diferentes fragmentos del programa. A esto se le llama resaltado de código.

Aquí hay una labor múltiple:

identificar todo el bloque de código fuente, diferenciándolo de párrafos precedentes o subsiguientes
respetar los espacios y saltos de línea dentro de ese bloque
establecer un tipo de letra especial y un color de fondo
identificar el lenguaje de programación y resaltar la sintaxis.

El resaltado se hace con la ayuda de un software llamado Pygments, que se instala junto a MkDocs. Tenemos una lista de lenguajes admitidos por Pygments en este enlace

Extensiones¶

El respeto del espaciado y saltos de línea se obtiene fácilmente sangrando cuatro espacios todo el código fuente. Pero las extensiones proporcionan más capacidades. MkDocs proporciona de serie dos extensiones:

Fenced code blocks, que proporciona una alternativa a los bloques de código sangrados
CodeHilite, que sirve para resaltar el texto.

Material for MkDocs sustituye estas dos extensiones por Superfences y Highlight, que tienen más posibilidades.

Escribiendo un bloque de código¶

Al utilizar las extensiones mencionadas, en lugar de usar un sangrado, los bloques de texto fuente se escriben como un párrafo cualquiera, pero colocando por delante y por detrás una línea formada por tres o más caracteres ~ o bien acentos invertidos. Por ejemplo:

Texto de un programa 
en lenguaje Java:

~~~~~~~~~~~~~~~~~~~~~
class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }
~~~~~~~~~~~~~~~~~~~~~

o bien

Texto de un programa 
en lenguaje Java:

``````````````````
class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }
``````````````````

Estas líneas delimitadoras no se mostrarán en el resultado final.

Resaltado¶

Para resaltar los elementos del programa en diferentes colores, tenemos que especificar el lenguaje de resaltado en la línea inicial que delimita el bloque:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .java
texto del programa
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

El punto es opcional. Podemos usar llaves y añadir un nombre identificador a todo el bloque:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.java #ejemplo-1}
texto del programa
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Para que el resaltado de código fuente funcione, necesitamos activar las extensiones:

markdown_extensions:
    - pymdownx.superfences
    - pymdownx.highlight

La labor de resaltado la hace Highlight, pero esta requiere la presencia de Superfences.

En el caso de bloques identificados al estilo tradicional markdown, mediante sangrado, Highlight también permite identificar el lenguaje añadiendo una primera línea al bloque. Por ejemplo:

Texto regular.

    :::java
    texto del bloque a resaltar

Mostrar números de línea¶

Al mostrar un programa en un manual técnico, a veces queremos hacer referencia a la línea número x. Puede ser de utilidad mostrar una numeración en el margen izquierdo:

class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }

Con la extensión Highlight, esto se activa en la línea de cabecera del bloque, añadiendo la palabra linenums y el valor inicial:

~~~~ .java  linenums="1"

texto de un programa java

~~~

Nótese que, por defecto, MkDocs construye una tabla sin celdas de cabecera y con dos columnas, la de la izquierda para números de línea y la de la derecha para texto fuente. Podemos hacer que el número de línea forme parte del texto si lo establecemos en el archivo de configuración mkdocs.yml. Lo veremos más adelante.

Resaltar líneas¶

Podemos resaltar determinadas líneas cambiando el color de fondo:

class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }

lo que se consigue añadiendo el argumento hl_lines tras el nombre del lenguaje:

``` java linenums="1" hl_lines="3 5"

texto del programa

```

Entre comillas se escribe la o las páginas a resaltar.

Para indicar un rango de la líneas x..y escribimos algo así como:

``` java hl_lines="1 3-5"

texto del programa

```

Lo que muestra:

class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }

Existe una diferencia importante entre las extensiones Fenced code blocks y Superfences. Los bloques delimitados con la primera no pueden sangrarse, por lo que no pueden formar parte de, por ejemplo, un elemento de lista o una cita. De ahí la conveniencia de usar Superfences.

InlineHilite¶

La extensión InlineHilite proporciona resaltado para fragmentos de código fuente dentro de un párrafo regular. Requiere activar highlight:

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.inlinehilite

Estos pequeños fragmentos de código se delimitan entre acentros invertidos. Tras el primer apóstrofo tenemos que escribir el lenguaje, precedido por los símbolos #!

Declarar una clase con la sentencia `#!java class NombreClase`.

Lo que muestra:

Declarar una clase con la sentencia class NombreClase.

Configurar Highlight¶

Podemos usar el archivo mkdocs.yml para configurar el comportamiento de Highlight. Veamos algunas opciones:

use_pygments controla si vamos a usar pygments para las labores de resaltado, o un script usando JavaScript:
```
markdown_extensions:
    - pymdownx.highlight:
        use_pygments: true
    - pymdownx.superfences
```
El resto de opciones aquí mencionadas asumen use_pygments: true

pygments_lang_class genera una clase CSS para identificar el lenguaje.

markdown_extensions:
    - pymdownx.highlight:
        use_pygments: true
        pygments_lang_class: true
    - pymdownx.superfences

auto_title muestra un título de cabecera del bloque indicando el lenguaje de programación.

markdown_extensions:
    - pymdownx.highlight:
        use_pygments: true
        auto_title: true
    - pymdownx.superfences

linenums: true añade por defecto números de línea a todos los bloques de código fuente.
linenums_style selecciona la forma de generar números de línea:
- linenums_style: table genera una tabla con dos columnas, la de la izquierda con números y la derecha con texto fuente.
- linenums_style: pymdownx-inline hace que los números de línea formen parte del texto fuente. Esto implica que, al seleccionar un fragmento de texto con el ratón, se incluyan también los números de línea.
- anchor_linenums: true genera un enlace para cada número de línea. Pasando el ratón podemos copiar el enlace.

Copiar y pegar¶

Con frecuencia acudimos a un manual técnico y copiamos los ejemplos al portapapeles. Esto se puede hacer seleccionando el texto con el ratón, pero Material for MkDocs proporciona un recurso adicional; muestra un icono a la derecha de los bloques de código fuente, que se muestra al pasar el ratón sobre el párrafo. Pulsando en el icono, se copia el texto al portapapeles.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

Esta característica ha de activarse en el archivo de configuración mkdocs.yml:

theme:
  features:
    - content.code.copy

Si no queremos activarlo a nivel global, podemos hacerlo individualmente para cada bloque de texto:

``` { .java .copy }
texto del programa
```

Nótese que el lenguaje utilizado se debe escribir antes. Ambas características van precedidas por un punto.

Similarmente, podemos activar el icono a nivel global y desactivarlo individualmente:

``` { .java .no-copy }
texto del programa
```

Si se trata de un texto genérico, podemos sustituir el nombre del lenguaje por la palabra .text, que no genera ningún resaltado de sintaxis:

``` { .text .no-copy }
bloque de texto
```

Añadir un títlo¶

Material for MkDocs proporciona la posibilidad de añadir un título a un bloque de texto fuente:

Programa de ejemplo

class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }

Esto se logra indicando una opción "title":

```java title="Programa de ejemplo"

class HelloWorld {

          public static void main (String args[]) {
               System.out.println("Hola Mundo");
          }

     }
```