Bloques de Código

MkDocs soporta de forma predefinida el uso de bloques de código. Sin embargo, MkDocs incluye varias prestaciones adicionales para los bloques de código tales como el remarcado de renglones, importación de código, copia de bloques con un click, etc.

Configuración

Hay prestaciones adicionales que se pueden habilitar, para ello se agrega al archivo de configuración:

Bloques de código - Configuración

# "mkdocs.yml"
theme:
  features:
    # prestaciones de código
    - content.code.copy         # botón de copia 
    - content.code.annotate     # botones de anotaciones emergentes

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite   # habilita remarcado de renglones
  - pymdownx.snippets       # habilita importar código de otros archivos
  - pymdownx.superfences    # habilita anidado de otros contenidos

Uso

Titulo de bloques

Es usa la propiedad title para asignar titulos a los bloques:

Formato de título

    ```txt title="Título de bloque"
    contenido
    ```

Título de bloque

contenido

Formato de datos

MkDocs obliga a asignar un formato para el bloque (txt, md, py, js, etc) para poder usar las propiedades del bloque , incluyendo title.

Remarcado y numeración de líneas

El remarcado de renglones específicos se hace con la propiedad hl_lines, en tanto que la numeración automática se activa mediante linenums:

Remarcado y numeración de líneas

  ```py title="Ej: funciones en Python" hl_lines="1-3 6"  linenums="1"
  def suma(a, b):
      """Una suma sencilla"""
      return a + b


  valor = suma(2, 3)
  ```

En el ejemplo, se especifica que deben remarcarse los renglones entre 1 y 3 ,

def suma(a, b):
    """Una suma sencilla"""
    return a + b


valor = suma(2, 3)

Observaciones:

• linenums permite elegir el Nº de renglón inicial;
• hl_lines permite remarcar tanto rangos de renglones mediane guiones como renglones aislados separados por espacios.

Numeración requerida

Tanto hl_lines como linenums exigen especificar al menos un numero

Anotaciones

Las anotaciones tienen su propia sintaxis para su uso dentro de bloques de código.

Formato de anotaciones

  ``` yaml
  # (1)!
  ```

  1.  El contenido emergente va aquí.

Formato de anotaciones

# (1)!

1. El contenido emergente va aquí.

Bloques en linea

Usando un shebang (#!) seguido de la abreviación de lenguaje se puede asignar un estilo a los bloques de código en línea embebidos en texto.

Inline code blocks

Ejemplo: la función `#!py range()` se usa para generar una secuencia de números.

Ejemplo: la función range() se usa para generar una secuencia de números.

Archivos embebidos

Con ayuda del plugin snippets MkDocs es capaz de renderizar archivos de texto dentro de los bloques de código. Para ello se escribe la secuencia --8<-- y continuación la ruta del archivo a renderizar entre comillas:

--8<-- "ruta_archivo"

Al ubicar la secuencia adentro del bloque de códigos MkDocs lo incorpora completo:

Archivo embebido - ejemplo

from time import  time, sleep

print(f"Tiempo actual: {time()}")
sleep(3)
print(f"Tiempo actual: {time()}")

snippets soporta el renderizado selectivo de renglones, agregando los números de línea tras la ruta. Notaciones:

Secuencia	Uso
--8<-- "ruta_archivo:n "	Sólo renglón n
--8<-- "ruta_archivo::n "	Hasta renglón n
--8<-- "ruta_archivo:n:m "	Renglones desde n hasta m

Ejemplo:

Archivo embebido - seleccion renglones

print(f"Tiempo actual: {time()}")
sleep(3)
print(f"Tiempo actual: {time()}")

--8<-- "ruta_archivo:nombre_seccion"

Ejemplo: renderizado de la sección funcion

Archivo embebido - marcado sección

# (archivo fuente)
def mi_funcion(x):
    pass

Archivo embebido - renderizado

def mi_funcion(x):
    pass

Ruta desde raíz

La ruta de archivo debe ser relativa al directorio raiz del repositorio, de otra forma no lo encuentra. Por ejemplo, si el archivo a renderizar se llama ejemplo.py y está ubicado en la ruta docs/mkdocs-material/referencia/ entonces la secuencia para el renderizado será:

--8<-- "docs/mkdocs-material/referencia/ejemplo.py"

Referencias

Sitio oficial - Code Blocks

PymDown Extensions - Snippets