Ruby in markdown article
This commit is contained in:
parent
c46de1eebf
commit
1440a77470
3
.vscode/settings.json
vendored
3
.vscode/settings.json
vendored
|
@ -1,5 +1,6 @@
|
||||||
{
|
{
|
||||||
"files.associations": {
|
"files.associations": {
|
||||||
"*.mdx": "markdown"
|
"*.mdx": "markdown"
|
||||||
}
|
},
|
||||||
|
"ltex.language": "en-US"
|
||||||
}
|
}
|
|
@ -2,69 +2,29 @@
|
||||||
title: Ruby extensions for Markdown
|
title: Ruby extensions for Markdown
|
||||||
date: 2023-01-15T16:19:00+01:00
|
date: 2023-01-15T16:19:00+01:00
|
||||||
tags: [Japanese, zola, hugo, astro]
|
tags: [Japanese, zola, hugo, astro]
|
||||||
draft: true
|
|
||||||
---
|
---
|
||||||
In Markdown there is currently no notation for adding ruby to East Asian scripts, however it is possible to add support for it by using shortcodes in SSGs.
|
|
||||||
|
Sadly, as far as I know CommonMark currently doesn't include anything about ruby in its spec. On top of that ruby is pretty uncommon, so it is pretty rare for any ruby extensions to exist. As I move through any new frameworks, I will try to document any simple solutions that I figure out.
|
||||||
|
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
### Japanese
|
|
||||||
{日本語}(にほんご)の{文法}(ぶんぽう)は{難}(むずか)しい
|
|
||||||
Remark: `{日本語}(にほんご)の{文法}(ぶんぽう)は{難}(むずか)しい`
|
|
||||||
Tera: `{{/* ruby(expr="日本語,にほんご;の;文法,ぶんぽう;は;難,むずか;しい") */}}`
|
|
||||||
|
|
||||||
### Chinese
|
| Language | Example |
|
||||||
{北}(Běi){京}(jīng)
|
| -------- | ------- |
|
||||||
{北}(ㄅㄟˇ){京}(ㄐㄧㄥ)
|
| Japanese | {日本語}(にほんご)の{文法}(ぶんぽう)は{難}(むずか)しい |
|
||||||
`{{/* ruby(expr="北,Běi;京,jīng") */}}`
|
| Chinese | {北}(Běi){京}(jīng)<br/>{北}(ㄅㄟˇ){京}(ㄐㄧㄥ) |
|
||||||
`{{/* ruby(expr="北,ㄅㄟˇ;京,ㄐㄧㄥ") */}}`
|
| Korean | {韓}(한){國}(국) |
|
||||||
|
| Vietnamese | {河}(Hà){內}(Nội) |
|
||||||
### Korean
|
| Other | I {love}(like) ruby! |
|
||||||
{韓}(한){國}(국)
|
|
||||||
`{{/* ruby(expr="韓,한;國,국") */}}`
|
|
||||||
|
|
||||||
### Vietnamese
|
|
||||||
{河}(Hà){內}(Nội)
|
|
||||||
`{河}(Hà){內}(Nội) `
|
|
||||||
`{{/* ruby(expr="河,Hà;內,Nội") */}}`
|
|
||||||
|
|
||||||
## Zola
|
|
||||||
The following is a snippet for the Tera templating engine which is inspired by Jinja2.
|
|
||||||
```jinja-html
|
|
||||||
<ruby>
|
|
||||||
{%- for item in expr | split(pat=";") -%}
|
|
||||||
{%- set sub_item = item | split(pat=",") -%}
|
|
||||||
{{- sub_item[0] -}}
|
|
||||||
{%- if sub_item[1] -%}
|
|
||||||
<rp>(</rp><rt>{{- sub_item[1] -}}</rt><rp>)</rp>
|
|
||||||
{%- else -%}
|
|
||||||
<rt></rt>
|
|
||||||
{%- endif -%}
|
|
||||||
{%- endfor -%}
|
|
||||||
</ruby>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Hugo
|
|
||||||
The following is a snippet for the Golang templating engine used by Hugo.
|
|
||||||
```html
|
|
||||||
{{- with .Get 0 -}}
|
|
||||||
<ruby>
|
|
||||||
{{- /* Generate the ruby markup */ -}}
|
|
||||||
{{- range split . ";" -}}
|
|
||||||
{{- $item := split . "," -}}
|
|
||||||
{{- $ruby := index $item 1 -}}
|
|
||||||
{{- index $item 0 -}}
|
|
||||||
{{- if $ruby -}}
|
|
||||||
<rp>(</rp><rt>{{- $ruby -}}</rt><rp>)</rp>
|
|
||||||
{{- else -}}
|
|
||||||
<rt></rt>
|
|
||||||
{{- end -}}
|
|
||||||
{{- end -}}
|
|
||||||
</ruby>
|
|
||||||
{{- end -}}
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## Astro
|
## Remark
|
||||||
|
Recently I moved to Astro, which generally uses JavaScript tools for parsing and manipulating markdown. In particular that's the Remark and Rehype from Unified.
|
||||||
|
|
||||||
|
When looking for a way to extend remark I first looked for an existing plugin which would allow me to automatically convert custom shorthands for ruby inserted into Markdown. I found a plugin called [remark-ruby](https://github.com/laysent/remark-ruby#readme), but honestly after looking at its source code I decided to hand roll my own solution. It just looked overcomplicated for something that should be simple and easy to modify (for me).
|
||||||
|
|
||||||
|
I was able to write a really simple and short solution using a pair of Regexes working in conjunction to split strings and replace custom ruby shorthands with HTML, which then passes through to Rehype.
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { visit } from "unist-util-visit";
|
import { visit } from "unist-util-visit";
|
||||||
import type { Node } from "unist-util-visit/lib";
|
import type { Node } from "unist-util-visit/lib";
|
||||||
|
@ -102,3 +62,49 @@ export default function ruby() {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
`{日本語}(にほんご)の{文法}(ぶんぽう)は{難}(むずか)しい`
|
||||||
|
|
||||||
|
## Zola
|
||||||
|
The following is a snippet for the Tera templating engine which is inspired by Jinja2.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<ruby>
|
||||||
|
{%- for item in expr | split(pat=";") -%}
|
||||||
|
{%- set sub_item = item | split(pat=",") -%}
|
||||||
|
{{- sub_item[0] -}}
|
||||||
|
{%- if sub_item[1] -%}
|
||||||
|
<rp>(</rp><rt>{{- sub_item[1] -}}</rt><rp>)</rp>
|
||||||
|
{%- else -%}
|
||||||
|
<rt></rt>
|
||||||
|
{%- endif -%}
|
||||||
|
{%- endfor -%}
|
||||||
|
</ruby>
|
||||||
|
```
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
`{{ ruby(expr="日本語,にほんご;の;文法,ぶんぽう;は;難,むずか;しい") }}`
|
||||||
|
|
||||||
|
## Hugo
|
||||||
|
The following is a snippet for the Golang templating engine used by Hugo.
|
||||||
|
```html
|
||||||
|
{{- with .Get 0 -}}
|
||||||
|
<ruby>
|
||||||
|
{{- /* Generate the ruby markup */ -}}
|
||||||
|
{{- range split . ";" -}}
|
||||||
|
{{- $item := split . "," -}}
|
||||||
|
{{- $ruby := index $item 1 -}}
|
||||||
|
{{- index $item 0 -}}
|
||||||
|
{{- if $ruby -}}
|
||||||
|
<rp>(</rp><rt>{{- $ruby -}}</rt><rp>)</rp>
|
||||||
|
{{- else -}}
|
||||||
|
<rt></rt>
|
||||||
|
{{- end -}}
|
||||||
|
{{- end -}}
|
||||||
|
</ruby>
|
||||||
|
{{- end -}}
|
||||||
|
```
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
`{{ ruby "日本語,にほんご;の;文法,ぶんぽう;は;難,むずか;しい" }}`
|
||||||
|
|
Loading…
Reference in a new issue