返回文章列表折页手记阅读全文

StarBlog Development Notes (19): Exploring Markdown Rendering Solutions

Preface In my view, the core of a blog website is the reading experience. During the development of StarBlog, the most time-consuming part was precisely the article display functionality. At first I hadn't figured out how to do backend rendering well, so I had to use the Editor.md component for frontend rendering as a stopgap. I wasn't satisfied with frontend rendering because of poor performance—the page would flash after loading, creating a disjointed feel that hurt the experience. Now that I've built a fairly complete backend rendering solution, frontend rendering can retire. This article introduces StarBlog blog development

曦远 (DealiAxy)2022.10.26约 26 分钟

目录18 个章节

Preface

In my view, the core of a blog website is the reading experience.

During the development of StarBlog, the most time-consuming part was precisely the article display functionality.

At first I hadn't figured out how to do backend rendering well, so I had to use the Editor.md component for frontend rendering as a stopgap. I wasn't satisfied with frontend rendering because of poor performance—the page would flash after loading, creating a disjointed feel that hurt the experience.

Now that I've built a fairly complete backend rendering solution, frontend rendering can retire. This article covers the various Markdown rendering approaches used while developing StarBlog (mainly focusing on backend rendering).

Two Approaches

Frontend Rendering

Rendering with the Editor.md component was barely satisfactory. I mainly chose it for its ability to generate a ToC (table of contents), but the generated ToC wasn't great either—I later forked the source and hacked it to make it somewhat better.

The hacking process is in this article: Hacking the editormd component to improve ToC rendering

I submitted a PR to the official repo for this ToC optimization, but got no response. Looking at GitHub, there are dozens of PRs, and the last commit was almost 4 years ago—looks like this project is truly dead...

Besides editor.md, there are a few other frontend options:

They all look decent. I didn't look into whether they have ToC. An expert on CNBlogs wrote a comparison article—interested readers can check it out in the references~

Backend Rendering

Currently the only usable Markdown library for C# seems to be Markdig. At first I complained that missing docs made it hard to use, and I even considered reinventing the wheel myself. Things have improved recently though—after studying several newly added official docs, I understand the library better. It really has a lot of features, is well designed, and is highly extensible~

So I'll stick with this for now~

My current approach is to use Markdig to generate HTML from Markdown, then display that HTML on the frontend, combined with style libraries like Bootstrap or github-markdown-css to beautify the article body, and JS libraries like highlight.js for syntax highlighting.

As for the article ToC, Markdig doesn't have a ready-made solution, so I rolled my own~

See this article: Generating a Markdown Document Table of Contents Tree in C#

It's actually a kind of hybrid approach~

The rest of this article focuses on backend rendering.

Handling ToC

The previous article already covered generating the table of contents tree in some detail, so I won't repeat all that here—I'll just cover the differences~

First parse the Markdown document and get all heading nodes

var headings = new List<Heading>();

foreach (var heading in document.Descendants<HeadingBlock>()) {
  var item = new Heading {Level = heading.Level, Text = heading.Inline?.FirstChild?.ToString()};
  headings.Add(item);
}

Then iterate and process them.

Originally I used the heading text directly as the anchor href attribute, but that doesn't work in practice. Based on testing, Markdig's rules for generating anchor IDs are as follows

For Chinese:

section
section-1
section-2
...

The number after section is the order of appearance among all Chinese headings, not among all headings.

For English, replace spaces and convert to lowercase ~~(other cases not considered; in fact special characters should also be replaced)~~

So when processing href, there are two cases. Use the regex [\u4e00-\u9fbb] to detect whether it contains Chinese characters.

var chineseTitleCount = 0;
for (var i = 0; i < headings.Count; i++) {
  var item = headings[i];
  var text = item.Text ?? "";
  if (Regex.IsMatch(text, "[\u4e00-\u9fbb]")) {
    item.Slug = chineseTitleCount == 0 ? "section" : $"section-{chineseTitleCount}";
    chineseTitleCount++;
  }
  else {
    item.Slug = text.Replace(" ", "-").ToLower();
  }
  // ...
}

Done

Styling

Bootstrap default styles

The default styles are okay, but something feels missing. Maybe I could look at the styles of various online Markdown editors~

github-markdown-css

As the name suggests, this is GitHub's markdown style

URL: https://www.npmjs.com/package/github-markdown-css

After installation there are three files

github-markdown.css: (default) Automatically switches between light/dark themes via @media (prefers-color-scheme)
github-markdown-light.css: Light theme
github-markdown-dark.css: Dark theme

The official site also has this sentence, but I don't know how to generate them myself—do I have to scrape the CSS from GitHub?

You may know that now GitHub supports more than 2 themes including dark_dimmed, dark_high_contrast and colorblind variants. If you want to try these themes, you can generate them on your own!

Install

yarn add github-markdown-css

Include

<link rel="stylesheet" href="~/lib/github-markdown-css/github-markdown-light.css">

Usage

<div class="markdown-body">
  @Html.Raw(Model.ContentHtml)
</div>

Result

It really has that GitHub flavor, but still no syntax highlighting

Syntax Highlighting

Currently using the highlight.js package, official site: https://www.npmjs.com/package/highlight.js

There are many other tools, but I won't go into them—this one is enough~

Download

To use it directly on a webpage you can't install via an NPM package; you have to download from: https://highlightjs.org/download/

If you don't want to download, you can use a CDN, but then only some languages are supported for highlighting.

There are so many languages, and surprisingly no select-all button. Checking them one by one is too much trouble, so I wrote a select-all script. Paste it into the browser console to select all, then download.

document.querySelectorAll('input').forEach( item => {
    if(item.getAttribute('type')==='checkbox') item.checked=true
})

Include

After downloading, unzip and put it under wwwroot/lib

<link rel="stylesheet" href="~/lib/highlight/styles/default.min.css">
<script src="~/lib/highlight/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

Or skip downloading and use a CDN directly

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/styles/default.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

Result

With syntax highlighting, it looks completely different

There are many other themes—lots of them under the styles directory. Just pick one when including the CSS.

Let me try a dark theme

Series Articles

References

JavaScript Parsing and Rendering Markdown - https://www.cnblogs.com/makalochen/p/14464519.html#5117019

_EOF_