「『Markdown文書』は一意ではない」ということを以前の記事で少し触れました。
Lightweight DITA（LwDITA）[1]のMarkdown形式「MDITA」について、もう少しみていきます。
まだ固まった仕様ではありませんので、記事で触れた挙動が変更される可能性があります。
内容に誤りがあった場合はおしらせください。
DITAについての説明は弊社サイトの情報ページ[2]やOASISのDITA Committe[3]、DITAコンソーシアムジャパン[4]といったサイトをご覧ください。
さて、LwDITAの目的ですが、ざっくりとは「複雑でとっつきにくい仕様だから、簡単な所だけ抜き出して簡単に書けるようにして、今までと違う層にも使ってもらおう」というものです。
LwDITA導入のためのOASISのページ[5]がDraftながら存在します。
説明が「DITAのこの機能をこう表現できる、この機能はない」といった方向によっていて、目的のひとつである「XMLで巨大なDITAを使っていない層へのアプローチ手法」としては難しいところです。このページのドキュメントのソースはGitHubリポジトリにあり、最終更新が2018年なので少し不安になりますが、SubCommitteのページには2020年5月のやり取りのログが公開されていたりするので動いているはずです。
Work In Progressな状態ではありますが、DITAをサポートするエディタのMarkdown対応が始まり、DITA Open Toolkit[6]でLwDITAのPreviewサポートが入った状況を考えれば、すぐに破棄される状況ではなさそうです。何より、そのような場合でも通常のXMLや他形式への変換がそう難しくないようにLwDITAは設計されています。
LwDITA以前にあった軽量記法への取り組みなどの歴史もあり、「現在使える仕組み」についての資料はWeb上から探すには
少し労力が要ります。正道としてはLwDITA導入のページ[5]からReferenceを辿っていくことになりますが、前知識のない状態でリーチするには難しい情報がそこそこあります。LwDITAについての書籍は1冊刊行されていて[7]、LwDITA SubCommitteeの現在のco-chairであるCarlos Evia氏によるものですから、ある程度信頼して良いでしょう。オンデマンド印刷版は4千円で手に入ります。
GitHubでホスティングされているリポジトリでLwDITA、というよりMDITAによるドキュメントのソースも幾つか見つかりますが、
基本的にセクション、リスト、リンク、コードブロックといった、GitBookなどでも登場するような要素のみ登場していました。
LwDITAの機能を使い倒すよりは、XML経由のMarkdownビルドに使用しているという印象です。
勿論それも付き合い方の1つではあるのですが、もう少しアピールできそうなポイントもありそうです。
今回はMDITAで使う記法について紹介します。次回はMDITAで使える（HTMLタグを書くことになりますが）DITAの機能を紹介する予定です。
DITAの、というよりLwDITAのファイルは基本的に、ひとつの事柄について扱うトピックを単位としてファイルを分割します。
トピックファイルを構成する要素は次の4つです。
- トピックタイトル
- Prolog（メタデータ）
- トピックのShort Description
- トピックの本文（Body）
MDITAの記法はCore Profileと呼ばれる基本の部分と、Extended Profileと呼ばれる部分で構成されます。
Extended ProfileはMarkdown方言（派生）の記法で有名、有用なものを採用して、Core ProfileではHTMLタグを書かなかければいけなかったところを補うようになっています。とはいえ、どれがCoreでどれがExtendedなのか、LwDITA導入のページ[5]でも表記にばらつきがあるようです。
まずCore Profileの部分を紹介します。
MDITAのトピックタイトルは次のように、<h1>レベルに変換されるような見出し記法で記述します。
行頭に「#」を置いて見出し内容とは半角スペースを挟む、ATX形式と呼ばれる見出しの記法です。
見出し内容の後に半角スペースを置き、「#」を重ねて見出し行、区切りを強調もできます。
# トピックタイトル
もうひとつ、Setext形式と呼ばれる記法もあります。<h1>:相当の見出し内容の行の下に「=」を並べる記法です。
トピックタイトル
===============
MDITAで段落の区切りは空行を挟みます（つまり、2連続で改行を入れます）。
基本的に要素同士の区切りは空白行です。
Short Descriptionはある意味簡単である意味難しいものといえるでしょう。トピックタイトルの行から1行空け、
最初の段落がそうなります。記法としてはそれだけですが、トピック全体を簡潔に記述した内容とする必要があります。
DITAのShort Descriptionの書き方として、
「Short Descriptionを重視し、そこで完結するなら本文は空でもよい」と薦められることを考えれば、簡易記法としては合理的です。
SubCommitteeのログを見ると、そのうちに記法のバリエーションが増えるかもしれません。
残りの部分は本文となります。
見出し項目はトピックタイトルの紹介で登場した、ATX形式とSetext形式の記法があります。
## ATXの見出し項目 ##
Setextの見出し項目
-----------------
仕様的な強制はありませんが、同じ文書内で同じ見出しレベルの記法を、
ATX形式とSetext形式で混在させるのは避けるべきでしょう。個人的には、後述するYAML Frontmatterの区切りに「---」を使うので、見出し項目にSetext形式を使うことは避けています。
一般的なMarkdownでのATX形式の見出し記法は、「#」を追加し<h3>から<h6>に相当する見出しが可能ですが、MDITAで使用可能なのは<h2>相当までです。この制限はトピック指向で文書を記述する際の目安になります。
つまり、これより低い見出しレベルが必要ならばトピックを分割すべきかもしれないということです。
箇条書きは行頭に「*」または「-」または「+」、半角スペースを空けて箇条書き内容を記述します。行区切りで次の箇条書き項目を記述します。
文書中で箇条書き記号の混在はしないようにしてください。入れ子の場合、行頭から親のラベルと半角スペース分の空白を空けて同じように記述します。番号付き箇条書きはCoreなのかExtendedなのか微妙な書き方をされていますが、「1」から「9」の数字始まりの半角アラビア数字と「.」または「)」、半角スペースを空けて箇条書き内容で同様に記述します。
* 箇条書き1
* 箇条書き2
* 2-1
1. 番号付き
2. 番号付き
表は単純な表を記述できます。見出し列、寄せ方向の指定ができますが、複雑な表は書けません。
縦の区切りを「|」、見出しと内容の区切りを「-」で記述します。「-」の個数はひとつでも構いません。行末の「|」は省略する場合もあります。内容の途中で表示を改行したい場合<br>が使えます。
寄せは区切りを「:---:」のように「:」で囲むと中央寄せ、「---:」なら右寄せというように表記します。
|見出し項目1|見出し項目2|
|----------|-----------|
| 内容1 | 内容2 |
整形済みテキストは、「“`」のに挟まれた箇所になります。コードブロックを意図している場合はExtended ProfileのHTMLタグでブロックを記述した方が確実かもしれません。
package main
...
インラインの記法として、次があります。LwDITA導入のページ[5]からはCore ProfileなのかExtended Profileなのか判然としないところですが、Markdownの基本的な記法であるはずです。
- 「
*」または「_」で囲んだ<em>。ただしXDITAだと<i> - 「
**」または「__」で囲んだ<strong>。ただしXDITAだと<b> - 「
[表示する文字](URL)」でリンクテキスト。 - 「
」で画像
インラインの整形済みテキスト記法の「`」囲いについては記述が見つけられませんが、
DITA-OTの処理を見ると有効のようです。
さて、Extended Profileについてです。
メタデータはYAML Frontmatterと呼ばれる記法で記述できます。ファイルの先頭、つまりトピックタイトルよりも先に、「---」と書かれた行に挟まれた部分に、設定記述用言語のYAML[8]を用いてトピックのメタデータを記述します。
メタデータに記述できる内容についてMDITAのイントロダクションページにはあまり記述がなく、例も次しかありません。
- id
- author
MDITA（のExtended Profile）と同じ表現力のXDITAにはDTDがあるので見てみると、
厳密には設定されていないようです。また、『Creating Intelligent Content with Lightweight DITA』[7]には次のようにあります。
Those attributes can provide information like the language of a topic, critical dates for a topic (creation, last revision, expiration, etc.), and much more.
DITA-OTのMarkdown Contentのシンタックスページは厳密にはMDITAのページではありませんが[9]、keyword, category, sourceといった項目をメタデータに設定している例があります。DITA的な文書の記述を行うなら、こういった情報を記載することはファイルの取り回しに有用でしょう。
---
id: topic-id
author: antenna
category:
- "markup"
keyword:
- "mdita"
- "markdown"
---
HTMLタグでの記述もExtended Profileの分類です。この部分の書き方の詳細はHDITAについての記述を読むことになります。
注意点として、HTMLタグで始めて閉じるまでの箇所の内部はMarkdownの記法は使えません。
先ほどのメタデータもHTMLタグで記述が可能です。
Creating LwDITAのサポートページと見なしてよいであろう、Carlos Evia氏のlwdita-bookのリポジトリ[10]に、MDITAの追加サポート記法として
定義リストと脚注の記法が記されています。
DT
: DD
空白行の後に行頭からタイトル<dt>、次行の行頭に「:」、半角スペースから<dd>、内容の記述を行います。空白行で終了、
行頭に「:」と半角スペース始まりで次の<dd>です。PHP Markdown Extra記法から、とあります。
脚注は、アンカーに「[^アンカーID]」、脚注内容を「[^アンカーID]: 内容」で記述します。
XML[^xml]は、…
[^xml]: Extensible Markup Languageは、…
他に、noteを記述する記法として「<div data-class="note">」がありましたが、MDITAでは非推奨となったということです。
次週にLwDITAで使えるDITAの機能について紹介する予定です。
参考資料
- [1] https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-lightweight-dita
- [2] アンテナハウス XML/DITAサービス
- [3] https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
- [4] DITAコンソーシアムジャパン
- [5] Lightweight DITA: An Introduction Version 1.0
- [6] DITA Open Toolkit
- [7] Creating Intelligent Content with Lightweight DITA
- [8] https://yaml.org/
- [9] https://www.dita-ot.org/dev/topics/markdown-dita-syntax-reference.html
- [10] https://github.com/carlosevia/lwdita-book
