Markup Reference for This Blog

This Blog consists of two parts: an old section written in Org Mode markup, and a new section written in Pollen. The code for generating content from the Org source is in /elisp, and we don’t talk about it. This reference describes the markup language I implemented on top of Pollen.

This reference assumes basic understanding of Pollen, one should read its manual, Pollen: the book is a program, before reading this reference.

The source of most of the tag functions described in this page can be found in /pollen.rkt, under the project root.

This page describes some common markups.

Stylistics

Bold and italic are the same as in html.

◊b{bold}, ◊em{italic}.

For Chinese, use 着重号 and 仿宋。

◊emph{着重号} and ◊zhalt{仿宋}。

Center a block with

◊center{
  content
}

For small caps, use ◊sc{...}, they will be rendered as small caps in html and normal caps in rss.

Use ◊om{...} for proportional oldstyle (0123456789); use ◊lm{...} for tabular lining (0123456789). The default is the font default, which is usually tabular lining. Tables and footnote references explicitly use tabular lining by default.

Headings

A blog post (or a single page of text) rarely needs headings beyond the second level, so This Blog only provides first and second level headings:

◊section{First level heading}
◊subsection{Second level heading}

Headings written in this way are collected in the table of contents and is numbered. To produce a heading that is not in the toc, nor numbered, use

◊h2{First level heading}
◊h3{Second level heading}

Hyperlinks and images

Hyperlinks are produced by

◊link["url"]{description}

For example,

◊link["https://www.gnu.org/software/emacs/"]{◊em{GNU Emacs}}

produces a link to gnu Emacs’s homepage: GNU Emacs.

Similarly, images are produced by

◊image["url" #:style "CSS style"]{Image description}

The description is mandatory, for accessibility purpose. The #:style argument is optional.

If one wish to include a caption under an image, they can write

◊fig{
  ◊image["url" #:style "width: 30%"]{Image description}
  ◊figcap{caption}
}

It would look something like

There are also some preconfigured styles:

img.half { width: max(50%, 300px); }
img.twothird { width: max(66%, 400px); }

which can be used as:

◊image["url" #:class "half"]{Image description}

Code and quote

Monospaced text is marked with

◊mono{content}

Inline code can be produced by

◊code{content}

Block code are produced by

◊bcode{
  content
}

Similar to a block code, a block quote is produced by

◊bquote{
  My name is Ozymandias, King of Kings;
  Look on my Works, ye Mighty, and despair!
}

Most of the time, code blocks on this blog are short and simple enough to not warrant syntax highlighting. For the exceptions, we can use the bcode-hl function:

◊bcode-hl['lang]{
  ...
}

For this to work, python must be in the path and pygment must be installed. See Pollen doc for more detail.

Lists

We use the same tags as in html for creating lists:

• ol for ordered list,
• ul for unordered list, and
• li for list items.

For example,

◊ol{
  ◊li{Love}
  ◊li{Peace}
  ◊li{War}
}

and

◊ul{
  ◊li{Streetcar}
  ◊li{Desire}
}

Tables

An easy way to produce a table is to use quick-table. In a quick-table, each line defines a row, each cell is separated by “|”. And the first row is considered the header.

◊quick-table{
  Name | Love Power | Exp Level
  Caroline | Strong | 1
  Kat | Medium | 3
  Annie | Strong | 2
}

The complicated way, and perhaps more powerful way, is to use html tags:

Note that the table above is wrapped in center tag, a table by itself is not centered.

Footnote

A reference to a footnote is produced by

◊fnref["id"]{referenced text}

And the definition of the footnote is produced by

◊fndef["id"]{explaination}

For example,

Today’s guest has 130 years of work experience in the
◊fnref["federation"]{federation}.

...

◊fndef["federation"]{Galactic Federation of Homo Sapiens}

It is recommended to put the footnote definition at the end of a section or subsection instead of the end of the whole
page¹, because a page on the web could stretch quite long.

Metas

Before the body starts, we declare some meta information used to produce the final page. The meta for this particular page looks like

◊define-meta[date]{<2021-09-03 Fri 00:14>}
◊define-meta[uuid]{b368e5a6-0c76-11ec-9a65-7b5b7ac199fc}
◊define-meta[tags]{Type}
◊define-meta[lang]{en}

◊meta{
  ◊title{Markup Reference}
}

The date meta contains an Org Mode time stamp² that’s down to either day or minutes. The uuid meta contains a uuid for this page. The tags meta contains a space-separated list of categories. For now there are Type, Emacs, Emacs_pkgs, Programming, Tech, Blog. The lang meta contains the ISO-639 language code of this page.

Since define-meta can only store plain text, This Blog provides the meta tag to store annotated metas. For the purpose of Notes, we only need to declare the title for the page. 《余日摇滚》 make more elaborate use of this feature.

For rss documents, set a rss-mode meta to indicate we are in generating rss, the value can be anything. Eg,

◊define-meta[rss-mode]{yay}

余日摇滚

余日摇滚在上面的基础上增加了一些自己的标记。

博客默认用中文字体显示汉字，因此日文需要手动标记。标记日文用

◊jpns{inline content}
◊bjpns{
  Block content
}

繁体中文用

◊trad{inline content}
◊btrad{
  Block content
}

韩文用 ◊korean{inline content}。

歌词用 lyrics 包裹起来，翻译在每行原文下面，用 trans 标记：

◊lyrics{
  ◊jpns{相约出来见面　16岁的夜晚}
  ◊trans{相约出来见面　16岁的夜晚}
  }

余日摇滚的 meta 用下面的格式：

◊define-meta[date]{<2021-09-02 Thu 21:08>}
◊define-meta[uuid]{98e190b6-0c6c-11ec-ae06-dfe062c79019}

◊meta{
  ◊cover{◊cover-img{first-impression--supernatural.jpg}}
  ◊artist{First impression}
  ◊title{Title of the single}
  ◊album{Title of the album}
  ◊year{1996}
}

一般单曲或是专辑的标题会加上链接：

◊album{◊link["https://youtu.be/G8smivxP7oo"]{supernatural}}

cover-img 这个标签里填专辑图片的文件名，博客会自动去 /rock/day/album 里找。

最终的结果就是每篇余日摇滚开头的专辑封面和信息，比如这个例子里的《余日摇滚第72日》。