Cómo editar ficheros Markdown en C# con Markdig

Markdig es una biblioteca de código abierto para .NET que proporciona una amplia gama de funcionalidades para trabajar con ficheros Markdown desde una aplicación escrita en C#.

Esta biblioteca se basa en un analizador sintáctico robusto y eficiente que puede leer y comprender la estructura de un fichero Markdown y convertirlo en un árbol de sintaxis abstracto (AST) fácilmente manipulable.

Con Markdig podemos realizar manipulaciones y transformaciones en el contenido de forma sencilla. También nos permite convertir ficheros Markdown a HTML.

El formato Markdown generado cumple con las especificaciones de CommonMark. También características adicionales como compatibilidad con GitHub Flavored Markdown, como tablas, listas de tareas y referencias de enlaces automáticos.

Markdig está diseñado para proporcionar un rendimiento rápido y eficiente. Utiliza técnicas avanzadas de análisis léxico y sintáctico para procesar rápidamente incluso documentos Markdown extensos.

Por otro lado, es posible añadir nuevas funcionalidades mediante extensiones. De esta forma, podemos agregar nuevas características, cambiar el comportamiento predeterminado del analizador y el renderizador, o incluso crear formatos de salida personalizados según sea necesario.

Cómo usar Markdig

Podemos añadir la biblioteca a un proyecto de .NET fácilmente, a través del paquete Nuget correspondiente.

Install-Package Markdig

Manipulación del Markdown

El árbol de sintaxis de Markdig nos permite leer y editar el contenido del fichero Markdow. Por ejemplo, podríamos obtener todas las imágenes, o el texto de todos los párrafos.

En este ejemplo, vemos como leer un fichero Markdown, obtener todos sus párrafos, y después seleccionar el texto.

var markdown = File.ReadAllText(path);
var document = Markdown.Parse(markdown);

var allParagrapgh = document.Descendants<ParagraphBlock>().ToArray();

var content = allParagrapgh.Select(x=> x.Inline.FirstChild).Cast<Markdig.Syntax.Inlines.LiteralInline>().Select(x=> x.Content).ToArray();

Como vemos el árbol de Markdig es muy potente. Aunque, como suele pasar en este tipo de librerías, la mayor dificultad es lidiar con las propiedades, ya que es muy extenso. Tirar de debugger para ir deduciendo las relaciones.

Añadir pipelines

El procesado de Markdown se puede personalizar con extensiones y pipelines. Por ejemplo, si queremos extraer el encabezado FrontMatter del documento en formato Yaml podemos hacer,

private static readonly IDeserializer YamlDeserializer =
	   new DeserializerBuilder()
	   .IgnoreUnmatchedProperties()
	   .Build();

private static readonly MarkdownPipeline Pipeline
	= new MarkdownPipelineBuilder()
	.UseYamlFrontMatter()
	.Build();

var content = File.ReadAllText(filepath);
var document = Markdown.Parse(content, Pipeline);
		
var frontmatter = document
	.Descendants<YamlFrontMatterBlock>()
	.FirstOrDefault();

Con eso obtendríamos un bloque frontmatter de nuestro fichero Markdown.

Conversión a HTML

Otra de las funcionalidades más importantes de Markdig es ofrecer una forma sencilla para convertir ficheros Markdown a HTML. A continuación, se muestra un ejemplo básico de cómo hacerlo,

var markdown = File.ReadAllText("documento.md");
var html = Markdown.ToHtml(markdown);

En definitiva, Markdig es una librería muy completa, que nos proporciona todas las funcionalidades que podamos necesitar para leer, manipular, o exportar formatos Markdown.

Es compatible con NETStandard 2.0, NETStandard 2.1, NETCoreApp 2.1 y NETCoreApp 3.1. Por lo que podemos usarlo en Windows, Linux, Android y macOS.

Markdig es Open Source, y todo el código y documentación está disponible en el repositorio del proyecto en https://github.com/xoofx/markdig.