2023-10-06T03:04:38UTC

hello world: about this place

put stuff together

This is a site written in extended^[1] common markdown and parsed^[2] into html, served via a Cloudflare R2 public bucket as a static site if nothing has changed when this note is published.

markdown to html

The toolchain was learnt from this post. We need npm and Node.js, along with the following packages: markdown-it, highlight.js, footnote plugin of markdown-it, attrs plugin of markdown-it, mathjax plugin of markdown-it. Installation:

# on node v18.15.0, npm 9.5.0
npm install --save markdown-it highlight.js markdown-it-footnote markdown-it-attrs markdown-it-mathjax3

The conversion part has little non-default settings. The code looks like:

var mdit = require('markdown-it');
var hljs = require('highlight.js');

// (some hard-coded html head here)

md = new mdit({
    highlight: function(str, lang){
        if (lang && hljs.getLanguage(lang)){
            try{
                return  hljs.highlight(str, {language:lang,
                                        ignoreIllegals:true,
                                        }).value ;
            }catch(__) {
                console.log('wut');
                return md.utils.escapeHtml(str);
            }
        }
    }
}).use(
    require('markdown-it-footnote')
).use(
    require('markdown-it-attrs')
).use(require('markdown-it-mathjax3');

// (read md, process md + update peripherals and finally write html)

Sidenotes:

• Highlight.js is the current syntax highlighter used by Stack Overflow sites, which were on Prettify of Google until 2020.
• Syntax highlighting is a github-flavored css included in highlight.js.
• A few custom ccs entries were used to modify text without touching the base html. For example, from this post i learnt to to insert decorative chars around quote blocks. Similarly, numbering of the headings is generated during rendering, method being learnt from this post which uses h{2,3,4,..}counter and counter-reset.
• Have close to zero experience with handling mathjax, but it is there due to the need to at least occassionally correctly typeset symbols. For example, $2\times$, $1\le 2$.

RSS/atom and delivery

The RSS advisory board has a RSS/atom validator. Before reading the specs, i worried about mismanaged timestamps might confuse aggregators, but seems deduplication is via id/guid which is more sane. I don't know much about the difference between RSS and Atom specs, the choice is arbitrary except for my preference to contain full texts in the feed. One unexpected problem is that the css-based text modification breaks down here, since css is absent from the feed.

Creation timestamps are manually written along with texts, and update timestamps are updated when a markdown re-parsed into html. The feed xml is assembled by a dumb python script, and uploading to R2 is a equally dumb bash script, in other words, human-powered. We will see how human errors balance against a more automatic workflow.