VFM の仕様設計について

@nosuke23

VFM の仕様設計について

@nosuke23

HTML

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Example</title>
  </head>
  <body>
    <section>
      <h1>Example<h1>
    </section>
  </body>
</html>
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Example</title>
  </head>
  <body>
    <section>
      <h1>Example<h1>
    </section>
  </body>
</html>

XML ベースの形式言語(HTML4.0~)
- 開始タグ及び終了タグによって区切られる要素で構造化される
要素を意味づけするためのセマンティックタグを提供する
- e.g. h1, section, figure
HTML は形式的であるが故に、人が直接記述及び閲読するにはユーザーフレンドリーでない

Markdown

https://daringfireball.net/projects/markdown/
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
Markdown はドキュメントの作成において、プレーンテキストの状態で読み/書きしやすいように設計されている

他の WYSIWYG エディターと比較して

利点
- プレーンテキスト
  - 読み/書きしやすい
  - 管理/保守しやすい
欠点
- 学習コスト

記法

Element HTML Markdown

Heading

Element	HTML	Markdown
Heading	`<h1>H1</h1>` `<h1>H1</h1>`	`# H1` `# H1`
Bold	`<strong>bold text</strong>` `<strong>bold text</strong>`	`bold text` `bold text`
List	`<ul> <li>Milk</li> <li> Cheese <ul> <li>Blue cheese</li> <li>Feta</li> </ul> </li> </ul>` `<ul> <li>Milk</li> <li> Cheese <ul> <li>Blue cheese</li> <li>Feta</li> </ul> </li> </ul>`	`- Milk - Cheese - Blue cheese - Feta` `- Milk - Cheese - Blue cheese - Feta`

<h1>H1</h1>
<h1>H1</h1>

# H1
# H1

Bold

<strong>bold text</strong>
<strong>bold text</strong>

**bold text**
**bold text**

List

<ul>
  <li>Milk</li>
  <li>
    Cheese
    <ul>
      <li>Blue cheese</li>
      <li>Feta</li>
    </ul>
  </li>
</ul>
<ul>
  <li>Milk</li>
  <li>
    Cheese
    <ul>
      <li>Blue cheese</li>
      <li>Feta</li>
    </ul>
  </li>
</ul>

- Milk
- Cheese
  - Blue cheese
  - Feta
- Milk
- Cheese
  - Blue cheese
  - Feta

記法

Markdown の記法はドキュメントを書く上で、比較的使用頻度の少ない記号(e.g. #)を使用した意味的、視覚的な非形式的な記法によって、主要なセマンティックタグに置き換えることで、読み/書きのしやすさを実現している
非形式的なマークアップ言語は、機能を増やせば増やすほど複雑さが増す
- 学習コストの増加
- 意図しない動作
- エスケープ処理
使用頻度の低い機能は HTML(形式的言語)を使用すればよい
使用頻度の高い(と予想される)機能を限定的に導入することで最適化しなくてはならない

関心事

VFM は CSS によって組版用の HTML を生成するための Markdown 拡張
HTML(4.0~) はドキュメントの構造化及び意味づけを行うためのものであり、スタイリングは CSS の責務
Markdown によるマークアップは意味的(、視覚的)に行われるべき
意味的非意味的
視覚的 **important**
非視覚的 important important

	意味的	非意味的
視覚的	`important`
非視覚的	`<strong>important</strong>`	`<span class="bold">important</span>`

方言

Webページ
静的サイト
- Jekyll
開発、コミュニケーション
- Github
変換
- Pandoc
プレゼンテーション
- slidev

ノート
- Obsidian
プログラミングノート

方言

移植性: 他の環境でも理想的に動作させることができるか、プレーンテキストの状態でも視覚的であるか
- 1つの Markdown ドキュメントは他の用途で使用される場合がある
親和性: ユーザーにとって馴染み深い記法か、追加の学習コストをともなうか
- Markdown の読みやすさは、既に Markdown を使用しているかにも拠る

結論

VFM は CSS によって組版用の HTML を生成するための Markdown 拡張
新たな機能の仕様を決定する際は以下を考慮し、 HTML からその記法に置き換えた場合に十分な優位性があるかどうか総合的に判断する
- 上記の目的において、仕様頻度が十分高い機能か
- 意味的、視覚的に読みやすく、また書きやすいか
- 他方言から/への移植性、親和性が高いか
- 直接的なスタイリングではなく、意味づけあるいは構造化を行うものか

さらなる利便性を求めて

CSSによるスタイリングはセレクターによって要素を指定する

strong {
  text-weight: bolder;
}
strong {
  text-weight: bolder;
}

スタイルと要素の多対多の関係性を抽象化するために、セレクターはセマンティックに命名される(セマンティックマークアップ)
セマンティックマークアップは規模が大きくなるほど、名前衝突を回避するのが困難になる
ローカルスコープを使用することで、グローバルスコープの汚染(名前衝突の可能性)を回避する
- https://github.com/css-modules/css-modules
Markdownでコンポーネントを宣言的(副作用を与えず)に使用してマークアップする(宣言的マークアップ)

実装案

./parent.md

:::

## Parent

:::

---
path: ./child.md
---
:::

## Parent

:::

---
path: ./child.md
---

./child.md

---
style: ./child.css
---

:::

## Child

:::
---
style: ./child.css
---

:::

## Child

:::

./child.css

div {
  border: 1px solid #000;
}
div {
  border: 1px solid #000;
}

実装案

./parent.html

<html>
  <head>
    ...
    <link rel="stylesheet" href="./child.css">
    ...
  <head>
  <body>
    <div>
      <h2>Parent</h2>
    </div>
    <div class="_child_someid">
      <h2 class="_child_someid">Child</h2>
    </div>
  </body>
</html>
<html>
  <head>
    ...
    <link rel="stylesheet" href="./child.css">
    ...
  <head>
  <body>
    <div>
      <h2>Parent</h2>
    </div>
    <div class="_child_someid">
      <h2 class="_child_someid">Child</h2>
    </div>
  </body>
</html>

./child.css

div._child_someid {
  border: 1px solid #000;
}
div._child_someid {
  border: 1px solid #000;
}