💾 Archived View for d.moonfire.us › blog › 2022 › 02 › 17 › mfgames-markdown-gemtext-1.2.1 captured on 2024-05-10 at 11:20:36. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-04-26)
-=-=-=-=-=-=-
As part of yesterday's post, I wanted to create a table in Gemtext that I could also produce in my Markdown to HTML pipeline. However, that was one step I skipped because it was overwhelming when I first wrote. However, the need to rant and warm pushed me over the board so I implemented tables.
Let's start with the biggest question. This is a library that uses Markdig[1] to parse Markdown and output gemtext[2] instead of HTML. This is the limited markup format used by Gemini browsers which is kind of a low-overhead and simplified browsing.
1: https://github.com/xoofx/markdig
2: https://gemini.circumlunar.space/docs/gemtext.gmi
The limitations of Gemtext are a big one. There are a few I struggle with, specifically a lack of italics and bolds, but it also doesn't let you have more than one link per paragraph, no Javascript, and generally is “what you see is exactly what you get”. For a writer, it fits nicely with that especially when used with a lovely client such as Lagrange[3].
3: https://github.com/skyjake/lagrange
I wrote the library inspired by md2gemini[4] which creates a “reasonable” output from Markdown which is my native writing format for novels and posts.
4: https://github.com/makeworld-the-better-one/md2gemini
At the moment, I don't have a SSL certificate to sign the library so I can't post it on NuGet, so I have my libraries at MyGet[5]. In specific, MfGames.Markdown.Gemtext[6] gives the information for downloading and using it.
5: https://www.myget.org/feed/Packages/mfgames
6: https://www.myget.org/feed/mfgames/package/nuget/MfGames.Markdown.Gemtext
Note, if you want want to multiple NuGet sources, the following `NuGet.config` works well for my packages:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="mfgames" value="https://www.myget.org/F/mfgames/api/v3/index.json" protocolVersion="3" />
</packageSources>
</configuration>
I have this checked into any project that uses them. I have… opinions about single source repositories but getting a SSL certificate isn't quite in my cards for at least half a year.
The source is located on Gitlab[7] along with ticket-tracking and the usual slew of tools.
7: https://gitlab.com/mfgames-cil/mfgames-markdown-gemtext-cil
The bulk of the code can be seen in the unit tests, but I want to work on better documentation. It's just waiting for Nitride[8]. Until then, here are some basics.
// using MfGames.Markdown.Gemtext; string input = "This is input."; string expected = "This is input."; string actual = MarkdownGemtext.ToGemtext(input); Assert.Equal(expected, actual);
This is pretty much how the base Markdig processing is done. I had to jump through a few extra hoops because of hard-coding, but overall, this is it.
The biggest thing is converting a paragraph with links into something Gemtext. There are a couple of formats, but my preferred (and the one I use on my Gemini version of this site[9]) is a table of links after the paragraph.
var input = string.Join(
"\n",
"This is a paragraph with an [inline](https://example.com) link.",
"Here is [another](https://example.org/) link, part of the same paragraph.",
"",
"This is a second paragraph, with a different [link](https://duck.com) in it.");
string actual = MarkdownGemtext.ToGemtext(
input,
new MarkdownPipelineBuilder()
.Use(new SetBlockLinkHandling(BlockLinkHandling.ParagraphEnd))
.Build());
Console.WriteLine(actual)
/* Output is:
This is a paragraph with an inline[10] link. Here is another[11] link, part of the same paragraph.
=> https://example.com 10: https://example.com
=> https://example.org/ 11: https://example.org/
This is a second paragraph, with a different link[12] in it.
=> https://duck.com 12: https://duck.com
Tables are not part of Gemtext. Before this version, if you passed in a table such as:
aaa|bbb|ccc --:|---|:-: 1|2|3 4|5|6
You would get everything on a single line.
aaa|bbb|ccc --:|---|:-: 1|2|3 4|5|6
With this version, you can pass a table parsing that produces a normalized table based on formatting using the excellent ConsoleTableEx[10] library.
10: https://www.nuget.org/packages/ConsoleTableExt
//using MfGames.Markdown.Gemtext;
//using MfGames.Markdown.Gemtext.Extensions;
MarkdownPipeline pipeline = new MarkdownPipelineBuilder()
.Use(
new GemtextPipeTableExtension(
new GemtextPipeTableOptions()
{
OmitPreformatLines = true,
ConfigureTableBuilder = (x) => x.WithFormat(ConsoleTableBuilderFormat.MarkDown),
}))
.Build();
string input = string.Join(
"\n",
"aaa|bbb|ccc",
"--:|---|:-:",
"1|2|3",
"4|5|6");
string expected = string.Join(
"\n",
"| aaa | bbb | ccc |",
"|-----|-----|-----|",
"| 1 | 2 | 3 |",
"| 4 | 5 | 6 |",
"");
string actual = MarkdownGemtext.ToGemtext(input, pipeline);
Assert.Equal(expected, actual);
I went with the library because I like how `ConsoleTableEx` will make sure everything is lined up. Plus, you can change the formatting to change the borders around and between the cells, different layouts, and the like. Basically, the options configured in the `ConfigureTableBuilder` lets the developer set the format instead of me deciding on a One True Way™️.
I have a couple minor little things with this library, but a lot of it is based on getting Nitride cleaned up and usable. This site uses Nitride and it runs nicely, but it isn't quite ready for prime time. So, I'm taking lessons learned, refactoring that library, and hopefully get it ready for the next big site (https://mfgames.com/).
Categories:
Tags:
Below are various useful links within this site and to related sites (not all have been converted over to Gemini).
https://d.moonfire.us/blog/2022/02/17/mfgames-markdown-gemtext-1.2.1/