Extensiones

Ya hemos visto que existen diferentes versiones de Markdown. La usada por MkDocs es Python Markdown, que se ajusta bastante bien a la versión original de markdown, aunque hay algunas diferencias de menor importancia.

MkDocs y su complemento [Python-Markdown] incorporan algunas extensiones que aumentan las capacidades de la sintaxis markdown. Por ejemplo, la extensión SmartyPants convierte las comillas, apóstrofos y otros caracteres en sus equivalentes tipográficos:

Símbolo	Será reemplazado por
'	‘ ’
"	“ ”
<< >>	« »
...	…
--	–
---	—

Las extensiones no tienen efecto si no las activamos en el archivo de configuración mkdocs.yml:

site_name: Mi proyecto de documentacion

theme:
  name: material

markdown_extensions:
    - smarty
    - tables
    - footnotes

En este ejemplo estamos activando tres extensiones. Además de SmartyPants, habilitamos la posibilidad de insertar tablas de datos y notas a pie de página en el documento.

Las extensiones pueden ser configurables. Por ejemplo, SmartyPants permite que solo tengan efecto determinados caracteres. Los valores por defecto son:

markdown_extensions:
    - smarty:
        smart_dashes: True
        smart_quotes: True
        smart_angled_quotes: False
        smart_ellipses: True
    - tables
    - footnotes
    - otras extensiones...

Además de las extensiones proporcionadas por [Python-Markdown], Material for MkDocs añade otra colección adicional, PyMdown, para enriquecer la experiencia proporcionada por MkDocs.

Por ejemplo, la extensión Keys permite mostrar teclas de forma gráfica:

Pulsar Enter para continuar...

Esto se consigue escribiendo:

Pulsar ++enter++ para continuar...

y activando el tema y la extensión en mkdocs.yml:

theme:
  name: material

markdown_extensions:
    - pymdownx.keys

Las extensiones PyMdown se especifican con el prefijo pymdownx seguido de un punto y el nombre de la extensión.

Veamos a continuación un conjunto de las extensiones más relevantes.