MultiMarkdown Sintaxis

¿Qué es MultiMarkdown?

De acuerdo a su página oficial:

MultiMarkdown o MMD, es una herramienta para ayudar a convertir texto plano mínimamente marcado hasta en documentos bien formateados, incluyendo HTML, PDF (a modo de LaTeX ), OPML o OpenDocument (específicamente, OpenDocument plano o «.fodt ’, que a su vez pueden ser convertidos en RTF, Microsoft Word, o prácticamente cualquier otro formato de procesador de textos).

MultiMarkdown fue desarrollado por Fletcher Penney para suplir las limitaciones del Markdown creado originalmente por John Gruber. Básicamente añade funciones extras a la sintaxis Markdown además de la salida de los diferentes formatos mencionados anteriormente —Markdown solo exporta al formato HTML—. También se basa en la tipografía “inteligente” para varios idiomas —adecuada para zurdos y citas del lado derecho—.

MultiMarkdown fue sufriendo algunas modificaciones, en primera instancia comenzó como un script en Perl modificado de Markdown.pl original.

Luego surgió MultiMarkdown v3 (aka “peg-markdown”), el cual se basó en peg-markdown de John McFarlane´s. Este fue escrito en C con el propósito de ser compilado en casi cualquier sistema operativo. Se utiliza una gramática de expresión de análisis sintáctico (parsing expression grammar – PEG) para definir la sintaxis.

Por último, MultiMarkdown v4, el cual es una reescritura completa de v3 utilizando el mismo PEG básico para analizar (Multi) texto Markdown. El resto es completamente reconstruido.

En fin, se puede escribir cualquier documento MultiMarkdown en el editor de texto que más prefieras —con formato de texto plano—, en cualquier sistema operativo, y será procesada la misma salida.

En este artículo expondré los siguientes ítems:

• Instalación de MultiMarkdown
• Sintaxis
• Metadatos (Metadata)
  • Metadatos “Variables”
  • Clave de Metadatos Estándar
• Tipografía inteligente
• Referencias cruzadas
• Enlace e Imagen Atributos
• Tablas
  • Fundamentos
  • Reglas
• Foonotes (Notas al pie)
• Citaciones
• Listas de definición
• Abreviaturas
• Bloques de código cercados —Fenced—
• Matemáticas
• Superíndices & Subíndices
• Sintaxis CriticMarkup
• Raw HTML
• File Transclusion (Transclusión de Archivo)
• Extensiones comodín
• Tranclusión preprocesamiento
• Nuevas líneas de escapado
• MultiMarkdown Línea de Comandos
  • Uso
  • Opciones Línea de Comandos

Instalación de MultiMarkdown

MultiMarkdown no está disponible como binario para sistemas Linux y UNIX. Las siguientes instrucciones son para compilar desde el código fuente:

Descargar las fuentes desde GitHub

En algún lugar de tu carpeta personal —en mi caso es ~/Descargas—, abrimos un terminal y ejecutamos:

cd ~/Descargas
git clone https://github.com/fletcher/MultiMarkdown-4.git

Ingresamos a la carpeta MultiMarkdown–4 y actualizamos los submódulos incluido peg:

cd MultiMarkdown-4
git submodule init
git submodule update

Compilamos:

make   

Alternativamente puedes corroborar que compiló correctamente, —se espera que falle una de las pruebas (listas ordenadas y desordenadas)—, el resto funcionará para todos los sistemas.

Ejecutamos:

make test-all | less 

dará una salida similar a esta:

22 passed; 0 failed.
Benchmark:  0 wallclock secs ( 0.02 usr  0.03 sys +  0.02 cusr  
0.00  sys =  0.07 CPU)

** It's expected that we fail the "Ordered and unordered lists" 
test **    
Ordered and unordered lists ... OK

Instalar (como root):

sudo make install    

por último instalar scripts de ayuda —p. ej., mmd, mmd2tex, mmd2odf etc.—:

sudo make install-scripts

De esta forma nos habrá instalado el binario y los scripts en /usr/local/bin.

Nota: También está disponible una versión en los ports de FreeBSD:

cd /usr/ports/textproc/multimarkdown
make install

Comprobamos que se haya instalado correctamente:

multimarkdown -v

Sintaxis

En el artículo Introducción a la sintaxis Markdown ya fue descripta en gran parte su sintaxis. Ahora se abordará solamente el subconjunto de funciones agregadas por Fletcher Penney que no se encuentran en el Markdown de Gruber, además de aquellas funciones de sintaxis que difieren mínimamente.

Metadatos (Metadata)

MultiMarkdown nos ofrece la posibilidad de incluir metadatos al comienzo de nuestros documentos, esto es útil si deseamos que se procesen algunos datos en la salida formateada, ya sea en HTML, LaTeX u ODF etc.

Aquí un ejemplo de metadatos:

Title:   MultiMarkdown Sintaxis 
Author:   Percaff_TI99  
Date:   Septiembre 2015   
Comment:   Ejemplo de un documento MultiMarkdown      
CSS:   file:///home/usuario/css/style_sudo.css 

El código fuente HTML resultante:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <title>MultiMarkdown Sintaxis</title>
    <meta name="author" content="Percaff_TI99"/>
    <meta name="date" content="Septiembre 2015"/>
    <meta name="comment" content="Ejemplo de un documento 
MultiMarkdown"/>
    <link type="text/css" rel="stylesheet" href="/home/usuario/\
css/style_sudo.css "/>
</head>

Al incluir metadatos se deben cumplir una serie de premisas:

• Deben comenzar en la parte superior del documento y no deben estar precedidos de líneas en blanco —de lo contrario saldrá el texto en la salida HTML u otro formato—. Se puede incluir “- – -” antes y después de los metadatos. También es posible introducir “…” al final de la línea de metadatos.
• Los metadatos constan de dos partes: La clave (key) y valor (value). La clave debe ir al principio de la línea y comenzar con una letra ASCII o un número, a continuación, los siguientes caracteres puede consistir en letras ASCII, números, espacios, guiones o caracteres de subrayado. El final de la clave se especifica con dos puntos (:).
• Luego de los dos puntos (:), viene el valor de metadatos. Puede consistir en prácticamente casi todos los caracteres. En el caso de tener varias líneas, se aconseja dejar sangría para evitar confundirse con metadatos adicionales. Así mismo, si el valor de metadatos incluye dos puntos (:), se deberá dejar sangría para evitar que nos interprete un nuevo par de clave-valor.
• Se recomienda dejar dos espacios al final de cada línea de metadatos para mantener una estructura más ordenada si se utiliza Markdown en lugar de MultiMarkdown para procesar el documento.
• Claves de metadatos son sensibles a mayúsculas y todos los espacios son eliminados en el procesamiento, p.ej., Base Header Level, baseheaderlevel, base headerlevel, son todos iguales.
• Los metadatos no deben incluir marcado MultiMarkdown, se procesa como texto sin formato.
• Una línea en blanco al final de los metadatos desencadena el comienzo del resto del documento.

Metadatos “Variables”

Podemos sustituir el valor de una clave de metadatos en el cuerpo de un documento. Su sintaxis sería la siguiente:

Definimos los metadatos —key: value—

foo:    Valor asignado A
bar:    Valor asignado B

luego en el documento insertamos las variables:

Este es un ejemplo de variable [%foo]

## Una variable en un encabezado [%bar] ##

Al procesar la salida, ya sea en HTML, ODF u otro formato, las variables %foo y %bar serán sustituidas por los valores que le hayamos asignados en los metadatos:

Este es un ejemplo de variable Valor asignado A

## Una variable en un encabezado Valor asignado B ##

Clave de Metadatos Estándar

MultiMarkdown tiene una serie de claves de metadatos estandarizados; así mismo, se pueden incluir más claves por nuestra cuenta, sin embargo, se pretende mantener una lista tan corta como sea posible.

Algunas de las claves estandarizadas:

• Author
• Affiliator
• Base Header Devel
• Biblio Style
• BibTeX
• Copyright
• CSS
• Date
• HTML Header
• Quotes Language
• LaTeX Author
• LaTeX Input
• LaTeX Footer
• LaTeX Mode
• LaTeX Title
• MMD Footer
• ODF Header
• Title
• Transclude Base

Voy a describir los ítems más usuales utilizados en el formato HTML:

Author: Este valor representa el autor del documento utilizado en LaTeX, ODF y RTF para generar información del título.

Affiliator: Incluye más información del autor —enlace a un sitio web, título académico, empleador, etc—.

Base Header Level: Cambia el nivel superior de la organización de nuestro documento.

Baseheaderlevel: 2

## Introducción ##

Esto puede ser útil cuando estamos escribiendo un documento corto, generalmente el nivel de cabecera comienza con <h1> en HTML. Con el ejemplo anterior asignamos el nivel de cabecera <h2>, de esta forma <h1> se convertirá en <h2>, y este en <h3>, así hasta completar el documento. Base Header Level le indica a MultiMarkdown que cambie al mayor nivel de división especificado.

También hay varios “sabores” de esta clave de metadatos —p.ej., LaTeX Header Level, HTML Header Level, ODF Header Level—.

CSS: Esta clave especifica una URL para ser utilizado como un archivo CSS para el estilo del documento procesado en HTML.

HTML Header: Si deseamos introducir una etiqueta HTML puro en los metadatos debemos utilizar esta opción. Básicamente sirve para instalar alguna aplicación de tercero para usar en nuestro documento.

Por ejemplo, usar un script de mermaid para procesar gráficos:

HTMLHeader:   <script src="mermaid.min.js"></script>
              <script>mermaid.initialize({startOnLoad:true});\
              </script>

Title, Date: (Título, Fecha) se explican por sí solas.

Transclude Base: Útil cuando utilizamos la función File Transclusion (Transclusión de Archivo), esta opción nos permite especificar la carpeta dónde se encontrarán los archivos o documentos que serán enlazados —incluidos— dentro de nuestro documento principal. En el caso de no especificar ninguna ruta —puede ser una ruta completa o relativa—, MultiMarkdown buscará en la misma carpeta donde se encuentra nuestro documento maestro.

MMD Footer: Se utiliza para especificar el nombre de un archivo que será incluido mediante el método File Transclusion, este será añadido al final del documento —como pie de página—. Es una función muy útil, ya que podemos insertar un archivo que contiene: Lista de referencias, abreviaturas, enlaces, notas, etc. Todo en un solo archivo, que se puede reutilizar en otros documentos.

En el caso de escribir un gran documento conteniendo documentos más pequeños, esto le permite utilizar una lista de todos los archivos, sin múltiples copias que se insertan en el archivo maestro.

En este ejemplo especifico en la sección metadatos, la carpeta Documentos para alojar los archivos de texto que serán agregados al final del documento maestro mediante Transclusión utilizando MMD footer:

Transcludebase: /home/usuario/Documentos
MMDfooter: texto.txt

Añadirá al final del documento el contenido del archivo texto.txt.

Tipografía inteligente

MultiMarkdown incorpora la herramienta SmartyPants de John Gruber además de la base Markdown para convertir puntuación “normal” en puntuación tipografía más “inteligente”.

Al igual que Markdown, MultiMarkdown convierte:

• Comillas rectas (’ y «) en comillas “rizadas”
• Acentos abiertos de estilos quotes («este») en comillas “rizadas”
• Guiones (- – y – – -) en guiones en- y em- dashes (guión corto & guión largo)
• Tres puntos (. . .) se convierten en puntos suspensivos…

Referencias cruzadas

Crear enlaces dentro de un documento —Hiperenlaces— es muy fácil, la sintaxis sería la siguiente:

[Texto de ejemplo][]

si existe un encabezado con el texto especificado Texto de ejemplo, se creará un enlace a él:

## Texto de ejemplo ## 

Para el siguiente ejemplo:

Está contemplado en la [Instalación de MultiMarkdown][]

creará un enlace a la sección Instalación de MultiMarkdown:

## Instalación de MultiMarkdown ##        

Fácil verdad; también podemos hacerlo de la siguiente manera:

En la [sección de Metadatos][Metadatos "Variables"] 

irá a la sección:

### Metadatos "Variables" ###

En el caso de haber varios encabezados con el mismo título, para eliminar esa ambigüedad se puede incluir una etiqueta. Por ejemplo, en un encabezado o sección Introducción añadimos la etiqueta entre corchetes:

## Introducción [MultiMarkdownIntroducción] ##

Esto permite utilizar [MultiMarkdownIntroducción] para referirse a esta sección en concreto, y no otra sección nombrada Introducción.

Además de los encabezados en el documento, se pueden incluir etiquetas para imágenes y tablas que luego pueden ser utilizadas para las referencias cruzadas también. Si se define un ancla —anchor— usando el mismo id que es utilizado por una cabecera, entonces el ancla definido tiene prioridad.

Este artículo fue procesado a HTML utilizando la herramienta MultiMarkdown, y como mejor ejemplo práctico, he incluido un [índice][Introducción a la sintaxis MultiMarkdown] utilizando la sintaxis explicada anteriormente, la cual se ilustra a continuación:

[Instalación de MultiMarkdown][]  
[Sintaxis][]  
[Metadatos (Metadata)][]  
[Metadatos "Variables"][]  
[Clave de Metadatos Estándar][]  
...
...
...

Esto trabaja con encabezados atx y settex-styles.

Enlace e Imagen Atributos

Su sintaxis ya fue explicada en este artículo, sin embargo hay algunas funcionalidades extras a la sintaxis de John gruber, como el añadido de atributos a la información de referencia del enlace que ya esta retirado del texto en sí y no perturba la legibilidad.

Su sintaxis:

Este es un formato ![imagen][] y [link][] con atributos.  


[imagen]: https://path.to/image "Image title" width=120px \
height=50px 

[link]: https://path.to/link.html/ "Link title" class=external \
style="border: solid black 1px;"

Por ejemplo:

Este es el logo de ![GUTL][] y el [sitio oficial][]


[GUTL]: http://gutl.jovenclub.cu/wp-content/uploads/2015/09/\
gutl_logo_invertido.png  width=115px height=63px

[sitio oficial]: http://gutl.jovenclub.cu "GUTL" class=external \
style="border: solid red 1px;" 

Mismo ejemplo in situ:

Este es el logo de y el sitio oficial

Con el ejemplo anterior se generará la anchura y altura de los atributos de la imagen y un borde alrededor del enlace. Los atributos deben continuar después de los datos de enlace/imagen, y pueden contener saltos de línea, pero deben empezar por el principio de la línea. El formato es atributo=valor o atributo=“valor de palabras múltiples”.

Imágenes

Un vistazo rápido a la sintaxis Markdown:

![Texto Alt](/ruta/a/img.jpg)
![Texto Alt](/ruta/a/img.jpg "Título opcional")


![Texto Alt][id]
[id]: url/a/img.jpg "Título opcional"

Además de poder utilizar atributos con las imágenes y enlaces, MultiMarkdown también añade otras características. En el caso de que una imagen sea la única cosa en un párrafo, esta será tratada como un elemento de nivel de bloque.

Por ejemplo, la siguiente sintaxis:

Esta imagen (![Alt text](/path/to/img.jpg))
es diferente de la imagen siguiente:

![Alt text](/path/to/img.jpg)

El código HTML resultante será:

<p>Esta imagen (<img src="/path/to/img.jpg" alt="Alt text;>)
es diferente de la imagen siguiente:</p>

<figure>
<img src="/path/to/img.jpg" alt="Alt text">
<figcaption>Alt text</figcaption>
</figure>

La primera de ellas sería una imagen en línea, obsérvese que la sintaxis está contenida entre paréntesis (). El segundo —en HTML— se envuelve en un elemento gráfico HTML <figure>. En este caso, el texto alternativo también se utiliza como un pie de figura, y puede contener la sintaxis MultiMarkdown —por ejemplo, negrita, cursiva, etc.—.

Tablas

Fundamentos

MultiMarkdown utiliza una sintaxis especial para la creación de tablas, en general es compatible con la sintaxis utilizada por Michel Fortin en PHP Markdown Extra.

Ej. de tabla con referencia:

|           |       Agrupación      ||  
 Cabezera A | Cabecera B | Cabecera C|  
------------|:----------:|----------:|  
Contenido   |  *largo de la celda*  ||  
Contenido   | **celda**  | celda     |  

Nueva sección | datos    | datos     |  
Más contenido | escapar '\|'         ||  
[Tabla de ejemplo (caption)][tabla de ejemplo] 

Esta es una [tabla de ejemplo]

Tabla con cabeceras en la primera columna:

|           |       Agrupación      ||  
 Cabecera A | Cabecera B | Cabecera C|  
============|:----------:|----------:|  
Contenido   |  *largo de la celda*  ||  
Contenido   | **celda**  | celda     |  

Nueva sección | datos    | datos     |  
Más contenido | escapar '\|'         || 

Obsérvese que la “Cabecera A” cuenta como línea divisora signos “=”

 

Reglas

Deberán tenerse en cuenta ciertos requisitos:

• Debe haber al menos una | por línea.
• La línea “separador” entre cabeceras y contenido de la tabla debe contener sólo |, -, =, :, ., +, o espacios.
• El contenido de la celda debe estar en una línea única.
• Las columnas están separados por |
• La primera línea de la tabla, y la línea de alineación/divisor, deben empezar por el principio de la línea.

Otras notas:

• Es opcional si se escribe tuberías (|) al principio y al final de líneas
• La línea “separador” utiliza ==== o – – – -, para indicar la línea entre el encabezado y la celda. La longitud de la línea no importa, pero debe tener al menos un carácter por celda.
• Para determinar la alineación se utilizan los dos puntos (:) para asignar a la izquierda :- – – – o derecha – – – -:, en el caso de centrar se utilizan dos puntos en cada extremo :- – – -:. La alineación predeterminada es a la izquierda. Si la línea de separación termina con +, a continuación, en las celdas de esa columna serán envueltos al exportar a LaTeX si son lo suficientemente largo.
• Para indicar que una celda debe abarcar varias columnas, entonces simplemente añadir tuberías adicionales (|) en el extremo de la celda, como se muestra en el ejemplo anterior. Si la celda en cuestión se encuentra al final de la fila; entonces, significa que las tuberías no son opcionales al final de esa fila. El número de tuberías es igual al número de columnas de la celda que debe unir.
• Se pueden usar marcado Markdown dentro de las celdas de la tabla.
• Los títulos de las tablas son opcionales, no obstante, de estar presente estos deben comenzar al principio de la línea e inmediatamente antes o después de la tabla. En el caso de especificar dos títulos —antes y después de la tabla— se privilegia el que está primero. El texto del título debe estar entre corchetes [].
• Si tiene un título, también puede tener una etiqueta, que le permite crear anclas que apuntan a la tabla. Si no hay una etiqueta, entonces el título actúa como etiqueta.
• Las celdas pueden estar vacías.
• Se pueden crear múltiples etiquetas <tbody> —para HTML— dentro de una tabla que tiene una sola línea en blanco entre las filas de la tabla. Esto permite a su CSS colocar bordes horizontales para enfatizar diferentes secciones de la tabla. Esta característica no funciona en todos los formatos de salida —por ejemplo, RTF y OpenDocument—.

Limitaciones:

• MultiMarkdown puede manejar la mayoría de las tablas, sin embargo no cubre todas la tablas para todas las personas. Si las tablas son muy complejas tendrás que crearlas a mano o utilizando una herramienta para tal fin, diseñada específicamente para el formato de salida. Sin embargo, debes considerar si una tabla es la mejor opción cuando está limitada en MultiMarkdown.
• Apoyo RTF nativo para las tablas es muy limitado. Si necesitas tablas más complejas, se recomienda usar el formato OpenDocument, y luego usando LibreOffice para convertir el documento a RTF.

Foonotes (Notas al pie)

Esta es otra de las debilidades de Markdown, la creación de foonotes, para escribir notas al pie en MultiMarkdown se utiliza la siguiente sintaxis:

Referencia:

Texto regular[^foonote]

[^foonote]: Texto de la nota al pie.

Ejemplo:

De acuerdo a la tabla de ANOVA[^ANOVA] no existen diferencias 
significativas.


[^ANOVA]: En estadística, el análisis de la varianza (ANOVA, 
ANalysis Of VAriance, según terminología inglesa) es una 
colección de modelos estadísticos y sus procedimientos asociados, 
en el cual la varianza está particionada en ciertos componentes 
debidos a diferentes variables explicativas. 

Nota al pie en la misma línea (Inline):

También es posible utilizar notas al pie en la misma línea, esto es particularmente útil si la nota es corta, no recomendaría este método si el texto es relativamente largo.

Texto regular[^Texto de la nota al pie]

Ej.:

Busque más información en el sitio GUTL.[^Grupo de Usuarios 
de Tecnologias Libres: <http://gutl.jovenclub.cu>]

Ambos ejemplos in situ —referencia/en línea—:

De acuerdo a la tabla de ANOVA[1] no existen diferencias significativas.

Busque más información en el sitio GUTL.[2]

Citaciones

Para citaciones, MultiMarkdown utiliza una sintaxis similar a la de los anclajes:

Mi mamá y la Estación Espacial Internacional comparten algo: ambas usan GNU/Linux.[p. 83][#Tensión:2014]

A continuación la descripción:

[#Tensión:2014]: Magnani Esteban. *Tensión en la red*. Creative 
Commons, 2014.

En el ejemplo anterior cité un párrafo de la página 83 —[p. 83]— de un libro especifico. Y si bien, no hay reglas en el formato de clave de citación que se utiliza —ej., [#Tensión:2014]— pero deben estar precedidos por el símbolo numeral (#), al igual que las notas al pie utilizan (^). Luego se describe la información bibliográfica de dicha referencia.

El localizador —p. ej., [p. 83]— se utiliza debido a que las citas son indistinguibles de las notas al pie en la salida HTML. Sin embargo no hay normas especiales sobre lo que puede ser utilizado como un localizador en el caso de usar uno. Así mismo, si prefieres omitir el localizador, simplemente hay que dejar un conjunto vacío de corchetes antes de la cita:

Mi mamá y la Estación Espacial Internacional comparten algo: ambas usan GNU/Linux.[][#Tensión:2014]  

Si se incluye una fuente en la bibliografía, que no fue citada, simplemente utilizar lo siguiente:

[Not cited][#clave_de_la_cita]

Luego:


[#clave_de_la_cita]: Información bibliográfica.

En el caso de “Not cited” no distingue entre mayúsculas y minúsculas.

Listas de definición

MultiMarkdown utiliza la misma sintaxis que PHP Markdown Extra para listas de definición, su sintaxis sería:

Término
:   Definición

Es decir, que consta de un término y en la siguiente línea seguido de dos puntos (:) la definición. Puede tener más de una definición por término, y también es posible tener más de un término por definición colocando cada término en una línea separada. Opcionalmente puede tener una línea en blanco entre el último término y la primera definición.

1er. Término
2do. Término
:   Definición a

o

1er. Término

:   Definición a
:   Definición b

2do. Término

 :   Definición c

De acuerdo al PHP Markdown Extra de Michel Fortin: Términos deben ser separados de la definición anterior por una línea en blanco. Las definiciones pueden extenderse en varias líneas, en cuyo caso deben tener sangría. Sin embargo, se puede olvidar de sangrar una definición que abarque varias líneas y todavía va a trabajar.

Además, en PHP Markdown Extra, todas las definiciones están envueltas en etiquetas <p>.

Un ejemplo de dos términos con una y dos definiciones respectivamente:

Aminoácido
:   Sustancia química orgánica en cuya composición molecular 
entran un grupo amino y otro carboxilo. 20 de tales sustancias 
son los componentes fundamentales de las proteínas.

Proteína
:   Sustancia constitutiva de las células y de las materias 
vegetales y animales. Es un biopolímero formado por una o 
varias cadenas de aminoácidos, fundamental en la constitución 
y funcionamiento de la materia viva, como las enzimas, las 
hormonas, los anticuerpos, etc.

:   Proteína cuyas cadenas de aminoácidos están unidas 
covalentemente a moléculas de otra naturaleza, como los lípidos, 
los hidratos de carbono, etc.  

 

Además las definiciones pueden contener otros elementos de bloque como: Listas, blockquotes u otras listas de definición.

Abreviaturas

Multimarkdown ofrece soporte para abreviaturas, básicamente se utiliza la misma sintaxis de Michel Fortin:

*[HTML]: Hiper Text Markup Language
*[W3C]: World Wide Web Consortium
*[GUTL]: Grupo de Usuarios de Tecnologías Libres

En este caso cuando utilicemos las palabras HTML, W3C o GUTL en el documento, se añadirá el marcado abbr.

Por ejemplo:

Se encuentra alojado en la biblioteca virtual de GUTL.

Se convertirá en:

Se encuentra alojado en la biblioteca virtual de <abbr title="Grupo de Usuarios de Tecnologías Libres">GUTL</abbr>.

En este artículo podrás comprobarlo en las abreviaciones de HTML y GUTL.

Una abreviatura con resultado de definición vacío, se omite el atributo title

Ejemplo:

R se distribuye bajo la licencia GNU GPL.

*[GNU GPL]:

Limitaciones:

• El nombre completo de la abreviatura es texto plano, no se procesará ningún marcado por MultiMarkdown.
• Abreviaturas no funcionan al exportar el documento a ODF.

Bloques de código cercados —Fenced—

En el Markdown de J. Gruber para crear bloques de código preformateado debíamos dejar sangría de 4 espacios, en MultiMarkdown además de el método mencionado, también se pueden crear bloques de código estilo fenced comenzando con 3 a 5 acentos abiertos, un especificador de lenguaje opcional —si se utiliza resaltado de sintaxis—, y deben terminar con el mismo número de acentos abiertos que comenzó.

Por ejemplo:

```python
class Person:

       # constructor or initializer
      def __init__(self, name): 
            self.name = name # name is data field also commonly 
known as instance variables

      # method which returns a string
     def whoami(self):
           return "You are " + self.name
```

Bloques de código cercados son particularmente útiles cuando se incluye otro archivo —p. ej., File Transclusion—, y se desea mostrar la fuente del archivo, no lo que el archivo se ve como cuando es procesado por MultiMarkdown.

También es posible usar resaltado de sintaxis utilizando la sección de metadatos:

HTMLheader: <link rel="stylesheet" href="http://yandex.st/\
highlightjs/7.3/styles/default.min.css">
            <script src="http://yandex.st/highlightjs/7.3/\
highlight.min.js"></script>
            <script>hljs.initHighlightingOnLoad();</script>

 

Matemáticas

MultiMarkdown utiliza mathjax, ya que la misma sintaxis es apoyada por mathjax en los distintos navegadores y LaTeX. Se utilizará la sintaxis de este último para introducir matemáticas a un documento MultiMarkdown.

Para habilitar el soporte mathjax en páginas web, hay que incluir un enlace a una instalación mathjax activa. El siguiente ejemplo ilustra la configuración en metadatos:

HTMLheader:     <script type="text/javascript"
                src="http://cdn.mathjax.org/mathjax/latest/\
MathJax.js?config=TeX-AMS-MML_HTMLorMML">
                </script>

Ejemplo:

Esta es una ecuación en bloque:

\\[ {x}_{1,2}=\frac{-b\pm \sqrt{{b}^{2}-4ac}}{2a} \\]


La siguiente ecuación matemática --- \\({e}^{i\pi }+1=0\\) --- se 
encuentra dentro de un párrafo de texto regular ---en linea---.    

La sintaxis contenida entre corchetes [] indican matemáticas en bloque, y entre paréntesis se utiliza para introducir sintaxis en linea. Además de la \ [\] y \ (\) sintaxis, se puede usar delimitadores estilo LaTeX —signo $—:

Esta es una ecuación en bloque:

$${x}_{1,2}=\frac{-b\pm \sqrt{{b}^{2}-4ac}}{2a}$$


La siguiente ecuación matemática --- ${e}^{i\pi }+1=0$ --- se 
encuentra dentro de un párrafo de texto regular ---en linea---.

Para que sea analizada correctamente como matemáticas, no debe haber ningún espacio entre el ‘$’ y la matemática real en el interior del delimitador, y debe haber espacio en el exterior.

 

Superíndices & Subíndices

En MultiMarkdown es relativamente fácil su sintaxis:

Superficie de 200m^2

Logaritmo en base 10: log~10

El subíndice no debe contener espacios en blanco o puntuación.

Exponenciales y subíndices más complejos:

x^(a+b)^

x~1,2~

Producirán:

Superficie de 200m²

Logaritmo en base 10: log₁₀

x^(a+b)

x_1,2

CriticMarkup

MultiMarkdown trae integrado CriticMarkup, esta interesante herramienta le permite al editor seguir los cambios en los documentos de texto plano, al igual que Markdown, grupo de caracteres distintivos permite destacar inserciones, supresiones, comentarios, sustituciones, sin recurrir a herramientas externas.

Sintaxis CriticMarkup

Hay que tener en cuenta que CriticMarkup se procesa antes que el manejo de MultiMarkdown, funciona casi como una capa separada en la parte superior de la sintaxis MultiMarkdown.

En MultiMarkdown tenemos 4 opciones para usar CriticMarkup:

• Deja la sintaxis CriticMarkup en su lugar (multimarkdown foo.txt)
• Aceptar todos los cambios que le da al nuevo documento (multimarkdown -a foo.txt)
• Rechazar todos los cambios que le da al documento original (multimarkdown -r foo.txt)
• Mostrar los cambios como aspectos destacados —solo funciona en HTML—. Esto se utiliza cuando se crean dos copias del documento —original y nuevo— (multimarkdown -a -r foo.txt)

La sintaxis CriticMarkup es la siguiente:

{--suprimir --}

{++añadir ++}    

{~~sustitución~>por otra~~}

{==resaltado==}

{>>comentario<<}

Aquí un ejemplo de lo que sería el texto original con los cambios previstos:

MultiMarkdown {--ya --} trae integrado CriticMarkup, esta 
interesante herramienta {++le ++} permite al editor seguir 
los cambios en los documentos de texto {~~simple~>plano~~}
{>>aquí sustituyo simple por plano<<}, al igual que 
{==Markdown==}, grupo de caracteres...

Luego el resultado aceptando/rechazando los cambios respectivamente:

Acepto los cambios (multimarkdown -a foo.txt):

MultiMarkdown trae integrado CriticMarkup, esta interesante 
herramienta le permite al editor seguir los cambios en los 
documentos de texto plano, al igual que Markdown, grupo de 
caracteres...


Rechazo los cambios (multimarkdown -r foo.txt):

MultiMarkdown ya trae integrado CriticMarkup, esta interesante 
herramienta permite al editor seguir los cambios en los 
documentos de texto simple, al igual que Markdown, grupo de 
caracteres...

En la siguiente imagen se ilustra la opción ‘-a -r’ dónde se muestran los cambios sugeridos:

 

Si estás en un ambiente colaborativo, o hay varios coautores trabajando en un mismo documento, CriticMarkup puede ser una muy buena alternativa para sugerir cambios en sus textos.

Raw HTML

Al igual que la sintaxis Markdown, pero con algunas mejoras, es posible utilizar (X)HTML crudo dentro de nuestro documento. Lo que ocurre con estas partes depende del formato de salida. También se puede utilizar el atributo de Markdown para indicar que el procesamiento MultiMarkdown debe aplicarse dentro de la etiqueta HTML a nivel de bloque. Esto se suma a la opción de línea de comandos «- -process-html» que provoca el procesamiento de MultiMarkdown dentro de todas las etiquetas HTML a nivel de bloque.

Ejemplo:

<div>Esto *no* es MultiMarkdown</div>

<div markdown="1">Esto *es* MultiMarkdown</div>

sin la opción – -process-html producirá:

<div>Esto *no* es MultiMarkdown</div>

<div>Esto <em>es</em> MultiMarkdown</div>

El atributo markdown=»1″ convierte el contenido de las etiquetas <div>’s de Markdown a HTML.

con la opción – -process-html:

<div>Esto <em>no</em> es MultiMarkdown</div>

<div>Esto <em>es</em> MultiMarkdown</div>

Comentarios

Este comentario será procesado por MultiMarkdown.

<!-- Este comentario no será procesado por MultiMarkdown -->

File Transclusion (Transclusión de Archivo)

Esta es otra característica que me ha gustado bastante de MultiMarkdown, la inclusión del contenido de un archivo de texto en el documento actual que se está procesando . Su sintaxis es muy simple:

Este es un texto regular del documento maestro.

{{archivo.txt}}

Más texto regular.

El contenido de archivo.txt se insertará dentro de este documento antes de ser procesado por MultiMarkdown. Además el contenido del archivo también pueden contener texto con formato MultiMarkdown.

Si por el contrario, se quieres mostrar el contenido del archivo.txt sin procesar, entonces deberás envolverlo como un bloque de código —estilo fenced—:

Este es un texto regular.

```
{{archivo.txt}}
```

Otro párrafo regular.

Algunos datos a tener en cuenta al insertar un archivo mediante Transclusión:

• Es recursivo, esto significa que será escaneado para ver si el archivo hace referencia a algún otro archivo.
• Se ignoran los metadatos que pueda contener el archivo insertado.
• Se puede utilizar el Transclude Base en la sección metadatos para especificar dónde debe buscar MultiMarkdown los archivos que se incluirán. Todos los archivos deben estar en la carpeta especificada. En el caso de no especificar una carpeta, entonces, MultiMarkdown buscará en la misma carpeta donde se encuentra el archivo principal.

En las siguientes imágenes se puede ver un ejemplo concreto de un documento incluido —tablas.txt—. En el 1er. caso el contenido con marcado es procesado, en el 2do. es cercado —fenced— para que MultiMarkdown no lo procese:

 

Extensiones comodín

A veces es posible que desee transcluir versiones alternativas de un archivo en función del formato de salida. Debemos utilizar la extensión “. *”. Tener MMD y elegir la versión apropiada del archivo —p. ej., foo.tex, foo.fodt, foo.html, etc.—

Incluya una versión diferente de un archivo basándose en el formato de exportación.

{{foo.*}}

Tranclusión preprocesamiento

Para realizar transclusión, sin necesidad de convertir a otro formato, se puede utilizar mmd como formato de salida:

multimarkdown -t mmd foo.txt

Esto solo funciona en modo de tranclusión básico, no admite extensiones comodín, ya que el formato de salida final no se conoce.

Nuevas líneas de escapado

Cabe recordar que en la sintaxis Markdown se deben dejar dos espacios al final de cada linea para indicar un salto de línea —introducía un <br />. Esto causaba molestias en ciertos usuarios, ya que los espacios finales suelen ser invisibles en el texto fuente. En MultiMarkdown se puede utilizar la barra invertida (\) para realizar un salto de línea.

Por ejemplo:

Una línea de texto.\
Esta es una nueva línea.

Luego hay que habilitar la función con la siguiente opción al procesarlo:

multimarkdown --escaped-lines-breaks archivo.txt  

Si esta opción no está activada, el comportamiento predeterminado será para tratar la nueva línea como un carácter de escape, lo que se traduce en que sólo aparece como un carácter de nueva línea en la salida. Esto significa que el comportamiento por defecto es el mismo que si el «\» no está en el archivo de origen.

MultiMarkdown Línea de Comandos

Es posible que en vez de utilizar la linea de comandos prefieras exportar el documento desde un editor de texto plano determinado, muchos tienen apoyo para MultiMarkdown, Sublime Text es una buena opción —aquí hay información que te puede interesar—, creo que aquellos que te permiten configurar comandos propios son la mejor alternativa para mantener un 100% de compatibilidad —Geany, podría ser uno de ellos—.

También puedes editar documentos desde cualquier editor especifico de Markdown, la mayoría tiene extensiones extras —Haroopad, CuteMarKed— para utilizar lo que se expuso en este post.

Dicho esto, yo voy a detallar como hacerlo desde la linea de comandos, soy de los que prefieren editar en texto plano. Además, en lo posible, me interesa conocer más en profundidad como funcionan los programas antes de utilizar interfaces de usuario.

Uso

Primero obtenemos más información de lo que puede hacer MultiMarkdown:

multimarkdown -h, multimarkdown --help

Convertir el texto plano en la salida HTML:

multimarkdown file.txt 

si queremos guardar los cambios utilizamos “>” para direccionar la salida:

multimarkdown file.txt > file.html

Además, MultiMarkdown utiliza el modo por lotes, es decir que guarda la salida con el mismo nombre de base que es de entrada, con la extensión .html —o .tex para la salida LaTeX—:

multimarkdown -b file.txt

Esto es particularmente útil cuando se quiere procesar varios archivos:

multimarkdown -b file1.txt file2.txt file3.txt

Producirá:

file1.html file2.html file3.html

En este caso no es necesario direccionar con “>” al utilizar la opción “-b”.

Crear una salida LaTeX en lugar de HTML:

multimarkdown -t latex file.txt > file.tex

También:

multimarkdown -b -t latex file.txt

Para LyX, OPML, y OpnenDocument (ODF):

multimarkdown -t lyx file.txt
multimarkdown -t opml file.txt
multimarkdown -t odf file.txt

Scripts —en modo por lotes— provistos por MultiMarkdown, aquí no se necesita utilizar “>” para guardar el archivo resultante —a menos que quieras especificar otro nombre—:

mmd file.txt
mmd2tex file.txt
mmd2opml file.txt  
mmd2odf file.txt

En el caso de mmd guardará la salida en HTML. Estos scripts están destinados a ser utilizados como accesos directos para las opciones de línea de comandos más comunes.

Opciones Línea de Comandos

multimarkdown -c file.txt

o

multimarkdown --compatibility file.txt

El modo compatibilidad produce una salida de MultiMarkdown a HTML compatible con la salida HTML del Markdown original. No obstante, características de sintaxis que no están presentes en el Markdown original se emitirán mediante el formato de salida normal MultiMarkdown.

multimarkdown --process-html file.txt

Como vimos anteriormente esta opción le dice a MultiMarkdown que procese el texto incluido dentro de las etiquetas HTML en el documento de origen. También se puede utilizar <div markdown=“1”>.

multimarkdown -o, multimarkdown --output=FILE

Es decir:

multimarkdown -o foo.html file.txt

Dirige la salida en el archivo especificado. Por defecto, la salida se dirige a stdout. El uso del modo por lotes elimina la necesidad de utilizar esta opción, sin embargo es muy útil para especificar un nombre de salida diferente.

multimarkdown -m, multimarkdown --metadata-keys

Muestra una lista de todas las claves de metadatos disponibles contenidas en un documento —una clave por linea—.

multimarkdown -e "metakey", multimarkdown --extract "metakey"

Emite el valor de la clave de metadatos especificada.

multimarkdown --random

Utilizar números de identificación aleatorios para las notas al pie. Útil cuando es posible combinar varios documentos HTML juntos, por ejemplo, en un weblog.

multimarkdown -s, multimarkdown --snippet

Forzar la salida de un snippet, esto significa que la información del encabezado y pie de página quedará afuera.

A partir de aquí todas las opciones están habilitadas por defecto:

multimarkdown --smart
multimarkdown --nosmart

Le dice a Multimarkdown si quieres utilizar la tipografía “inteligente”, similar a la de John Gruber SmartyPants

multimarkdown --notes
multimarkdown --nonotes

Utilizar o no, notas al pie.

multimarkdown --labels
multimarkdown --nolabels

Añadir atributos id a los encabezados.

multimarkdown --mask
multimarkdown --nomask

Decirle a MultiMarkdown que enmascare direcciones de correo en la salida HTML.

---

Más a saber

MultiMarkdown es bastante más que lo expuesto, he dejado algunas funciones de lado, principalmente lo referido a otros formatos como: BiTeX, LaTeX, LyX y algunas funciones muy técnicas. Mi objetivo en esta entrada es mostrar los conceptos básicos de MultiMarkdown y reflejar las funcionalidades extras con respecto al Markdown de John Gruber, sobre todo en lo que refiere al formato HTML —espero haberlo logrado—.

Sin embargo si te interesa profundizar tus conocimientos, tienes abundante información técnica y detallada —en inglés— para descargar en formato PDF. Y en la carpeta cheat-sheet se encuentra un “ayuda memoria” sobre la sintaxis Markdown y MultiMarkdown en español e inglés respectivamente.

---

 

Descargar MMD_Users_Guide.pdf

Descargar Guía rápida - cheat-seet.zip

 

Fuente:

http://fletcherpenney.net/multimarkdown/
http://www.michelf.com/projects/php-markdown/extra/
https://es.wikipedia.org/wiki/Transclusi%C3%B3n

---

Artículos relacionados con lo que acabas de leer:

• GUTL pasa a formar parte de la web de noticias: PlanetaLibre
• Publica en Hugo con emacs-easy-hugo
• Hugo: Generador de sitios web estáticos
• Editor de Markdown CuteMarkEd + Compilación
• Introducción a la sintaxis Markdown

---