660.txt

[20] [DFN[[RUBY[Markdown][マークダウン]]]] は、[[テキスト]]系[[マーク付け言語]]の一種です。

[21] [[GitHub]] など[[エンジニア]]向け製品が採用したことで普及し、
世界的に使われるようになりました。しかし製品ごとに大きく異なる[[方言]]のため[[相互運用性]]は絶望的に低い状態にあります。

* 代替

[65] 長期保存される[[文書]]の場合、互換性のために必要な場合を除き、 [[HTML]] など他の[[ファイル形式]]を検討するべきです。

* 仕様書

[17] [[Markdown]] には様々な[[方言]]があり、[[標準]]が存在しません。
[[標準化]]の試みが複数ありましたが、相互に矛盾しており、
[[相互運用性]]は存在しないと言わざるを得ません。

[53] 近年 [[GitHub Flavored Markdown]] が人気を博しており、
これが[[事実上の標準]]と言われることもあります。しかし[[仕様書]]は存在せず、
[[GitHub Flavored Markdown]] 対応を謳う実装もそれぞれ異なる拡張を施しているなど、
「有力な[[方言]]」以上のものと位置づけるのは難しそうです。

[76] [[GitHub]] を含むいくつかの実装者が参加して [[CommonMark]]
の[[標準化]]が進行しています。これがもっとも「標準」
に近い[[仕様書]]のようです。しかし [[GitHub]]
その他の実装は [[CommonMark]] を独自に拡張したものですから、
これだけ実装すれば済むというものにはなっていません。

* 方言

[18] [[Markdown]] には色々な方言があります。

[FIG(middle list)[
- [[Markdown Extra]]
- [[GitHub Flavored Markdown]] (GFM)
- [[CommonMark]]
- [[vfmd]]
- [[Markdown Extended]]
- [[でんでんマークダウンの記法]]
- [[Bikeshed]]
- [[Ecmarkdown]]
- [[Qiita::Markdown]]
- [[Markdown for Apple News Format]]
- [[kramdown Syntax]]
- [[kramdown-rfc2629]]
- [[grammarkdown]]
- [[MSON]]
- [[sgmljs.net Markdown]]
- [[R Markdown]]
- [[MultiMarkdown]]
- [[Jatdown]]
- [[Pandoc Markdown]]
- [[Pandoc2rfc]]
- [[Softcover-flavored Markdown]]
- [[Spec Markdown]]
- [[ScholarlyMarkdown]]
- [[CTAN Mark­down]]
- [[Markdown Survey Format]]
- [[Stobo Flavored Markdown]]
- [[はてなブログのMarkdown]]
- [[MackerelのMarkdown]]
- [[Marp’s Markdown]]
- [[KibelaのMarkdown]]
- [[Mmark]]
- [[ReSpec]]
- [[BitbucketのMarkdown]]
- [[Tracker-Flavored Markdown]]
- [[Discount]]
- [[Wiki formatting (Markdown)]]
- [[DocFX Flavored Markdown]] (DFM)
- [[GitLab Flavored Markdown]] (GFM)
- [[Tracker-Flavored Markdown]]
- [[Garrett-Flavored-Markdown]]
- [[Softcovered-flavored Markdown]] (SFM)
- [[Gerby Flavored Markdown]] (GFM)
- [[Habrahabr Flavored Markdown]] (HFM)
- [[athena flavored markdown]] (AFM)
- [[Adam Flavored Markdown]] (AFM)
- [[Baioh Flavored Markdown]] (BFM)
- [[BacklogのMarkdown]]
- [[Shotgun Markdown]]
- [[CommonMarkのMarkdown]]
- [[JSMD]]
- [[Vivliostyle Flavored Markdown]]
]FIG]

[44] 同じ方言に対応していると主張する実装であっても、更に細かい方言である場合があります。
(各項を参照。)

[19] 同じものを実装すると主張するソフトウェア同士でも解釈が一定しないことは普通です。
同じ会社の別の製品や、場合によっては同じ製品の異なる版同士で、
異なって解釈されることもよくあります。

[EG[
[45] 例えば[[ネイティブアプリケーション]]版で[[プレビュー]]を見ながら
[[Webサイト]]に投稿したら、 [[Webページ]]では違って見えることがあります。
]EG]

[38] ある製品向けに記述した [[Markdown]] の文書を、無変換でそのまま他の製品に完全に移植できることは期待しない方が安全です。

[77] 
方言名 (略称) 自体が既に衝突しているとかいう状況には[[草不可避]]wwww

[78] 
「○FM」全部埋まっているのでは?と思ったけど全然埋まっていないwwww
[[スクランブリングコードD]]さんがんばれwwwww

-*-*-

[54] [[Typetalkメッセージ書式]]は [[Markdown]] の一部構文に対応していますが、
それ自体が [[Markdown]] であるとは主張していないようです。

* 構文

[40] 
[FIG(short list)[
- [[HTMLタグ]]
- [[絵文字]]
]FIG]

* MIME型

[22] [[IETF]] は [DFN[[[RFC 7763]]]] で[[MIME型]]
[DFN[[CODE(MIME)@en[text/markdown]]]] を規定しています [SRC[>>15]]。

** [CODE(MIME)@en[variant]] 引数

[23] 方言問題のため [CODE[variant]] [[引数]]を定義していますが、
これは[[ヒント]]とされており [SRC[>>15]]、
一応は[[IANA登録簿]] [SRC[>>24]] も用意されているものの、
その値を用いる義務もありません。

[50] つまり一応[[方言]]問題の対策は用意したというポーズだけで、
実際何の役にも立ちません。どのような値が与えられた時受信者がどう解釈するべきかも規定されていません。
例えば未知の値を指定された時や、指定された値と実際の内容に齟齬がある時、
指定された[[方言]]に対応していない時などに、
どのように動作するべきかはまったく不明です。

[51] [CODE[variant]] が指定されない時に内容をどう解釈するべきなのかも不明です。

** [CODE(MIME)@en[charset]] 引数

[26] [CODE(MIME)@en[charset]] [[引数]]があり、[[必須]]とされています [SRC[>>15]]。

[27] [[RFC 6838]] に従ったものだ [SRC[>>15]] と言っていますが、
それは[[政治的に正しい]]のかもしれませんが、
[CODE(MIME)@en[text/plain]] や [CODE(MIME)@en[text/html]] で
[CODE(MIME)@en[charset]] [[引数]]が正しく運用されてこなかった歴史を踏まえると、
この規定に意味があるのかは謎です。

[28] [[RFC]] は [[Markdown]] の仕様書で[[文字コード]]が規定されていないといっていますが、
そもそも、今の時代、 [[UTF-8]] 固定の実装が多いのではないかという気もします。
[CODE(MIME)@en[charset]] 引数が指定されない場合にどう扱うべきなのかは不明です。

;; [56] [[Markdown]] が[[文字列]]の構文を定めるものだとすると、
その[[文字列]]を[[プロトコル]]の[[バイト列]]でどう表現するか、
[[プロトコル]]の[[バイト列]]をどう解釈するべきかを規定することこそが[[プロトコル]]の識別子である
[[MIME型]] [CODE(MIME)@en[text/markdown]] の[[仕様書]]の役割だと思うのですが...


** その他の引数

[29] 更に他の任意の[[引数]]も使える [SRC[>>15]] とされています。
方言ごとに[[引数]]の意味を定めるべきだと言っていますが、
[CODE[variant]] 省略時に使用してはならないとの規定もありません。
[CODE[variant]] [[引数]]の制約もあってないようなものですから (>>23)、
実質的に標準化を放棄しているだけです。

[25] そもそも [[MIME型]]の[[引数]]というもの自体の[[相互運用性]]と[[可搬性]]がほとんどない現状で、
これらの定義すら曖昧な[[引数]]もほとんど役に立ちそうにありません。
[[実装]]は[[引数]]をすべて無視するべきですし、[[著者]]は[[引数]]を使うべきではありません。

** [CODE[text/x-markdown]]

[60] 
[DFN[[CODE[text/x-markdown]]]] が使われることもあります。

[REFS[

[61] 
[CITE[Beta API docs · CPAN-API/cpan-api Wiki]]
( ([TIME[2013-03-04 06:52:23 +09:00]] 版))
<https://github.com/CPAN-API/cpan-api/wiki/Beta-API-docs>

[FIG(quote)[
[FIGCAPTION[
[62] [CITE[はてなブログAtomPub - Hatena Developer Center]]
([TIME[2016-03-21 10:48:28 +09:00]] 版)
<http://developer.hatena.ne.jp/ja/documents/blog/apis/atom>
]FIGCAPTION]

> contentにははてなブログに登録されたシンタックスと解釈されたオリジナルな文面が記載されます
> type属性には以下の3つの値のいずれかが付与されます。
> text/html 見たままモード
> text/x-hatena-syntax はてな記法
> text/x-markdown マークダウン記法

]FIG]

[FIG(quote)[
[FIGCAPTION[
[48] [CITE@en[Markdown | GitHub Developer Guide]]
( ([TIME[2016-12-21 11:10:42 +09:00]]))
<https://developer.github.com/v3/markdown/>
]FIGCAPTION]

> The raw API is not JSON-based. It takes a Markdown document as plaintext (text/plain or text/x-markdown) and renders it as plain Markdown without a repository context (just like a README.md file is rendered -- this is the simplest way to preview a readme online).

]FIG]

]REFS]

* 素片識別子

[30] [[RFC]] は、[[素片識別子]]は方言次第としつつ、独自の構文も定めています
[SRC[>>15]]。

[31] 独自の構文は、 [CODE(MIME)@en[application/x-www-form-urlencoded]]
風ではありますが、曖昧な説明があるだけです。

[32] [CODE[[[line=]]123]] のようにして、[[行]]を指定できます [SRC[>>15]]。
この [CODE[line][line=]] は [[RFC 5147]] [CODE[text/plain]] [[素片識別子]]の
[CODE[line][line=]] と同じ意味であり、 [[[N[0]]起算]]とされています [SRC[>>15]]。
また [CODE[[[line=]]10]] が''入力の'' [N[11]] 個目の[[行]]を表すと例示されています
[SRC[>>15]]。
[[Markdown]] の処理の結果の[[行]]は入力の[[行]]とは異なるかもしれませんし、
[[Markdown]] として解釈される構文のみを含む[[行]]で変換により消失するかもしれませんし、
そもそも[[行]]という概念がない形式に変換される可能性すらあるでしょう。
しかしそうだとすると[[素片識別子]]は [[Markdown]] [[ソースコード]]の表示には使えても、
変換結果には使えないかもしれません。
更には、[[改行]]の表現は環境によって異なるので実装は注意が必要 [SRC[>>15]]
だとありますが、具体的にどうしろとは書かれておらず
([[RFC 5147]] もいろいろな可能性を挙げるだけで処理方法は明確にしていません)、
[[相互運用性]]への意欲がまったく感じられません。
こんなものを使えと言われても無理でしょう。

[33] 他の[[引数]]とは [CODE[&]] で区切れます。方言は追加の引数を規定できます。 [SRC[>>15]]

[52] [[素片識別子]]に対応している実装があるのかは不明です。

* API

[14] [[Markdown API]]。

* 互換性と相互運用性

[46] [[Markdown]] の実装は色々あってそれぞれに異なる解釈があり、
同じ実装の異なる版で動作が異なることもよくあります。

[47] [[アプリケーション]]の開発者は、独自の方言を新たに作るべきではありません。
既存の[[ライブラリー]]があれば、それを利用するべきです。

[49] ただし、一度 [[HTML]] などに変換したら終わりの場合はともかく、
長期的に保存されるデータの場合は、利用する[[ライブラリー]]が継続的に適切にメンテナンスされる見込みがあるか、
慎重に判断する必要があります。バージョンアップしたら古いデータの解釈が変わってしまうというリスクがあります。

[37] 実装によっては、色々な[[方言]]の仕様を取り込んだ結果機能として破綻しているものもあります。

[EG[
[36] [[はてなブログのMarkdown]]は出自の異なる2種類の[[脚注]]構文を含んでおり、
それぞれ違った形で [[HTML]] として出力されるようです。
]EG]

[39] 最悪[[プレインテキスト]]としてほぼ解釈できるとはいえ、重要な文書は [[Markdown]]
で記述しない方が安全です。

[57] 
書き慣れている人も多いので[[下書き]]形式としては便利かもしれませんが、
中長期的に保存したい[[文書]]や[[情報交換]]目的に採用するのは考えものです。

[EG[
[58] 多くの[[利用者]]と大量の[[マークダウン]]データを抱える [[GitHub]]
は、[TIME[2017年][year:2017]]に大規模な非互換変更を実施しました。
困惑する[[利用者]]も少なからずいたようですが、
予告なく強制的に実施され、黙って従う他無かったようです。 ([[GFM]] 参照。)

[59] 
[[GitHub]] すらこのありさまなのですから、 [[Markdown]] はそんな儚いものとでも理解するしかないのでしょう。

]EG]

* 関連

[34] [[RFC 7763]] は、 [[Markdown]] の[[プレビュー]]に使う [[MIME型]]を指定するための
[CODE(MIME)@en[Content-Disposition:]] [[ヘッダー]]の
[CODE(MIME)@en[preview-type]] [[引数]]を定義しています。

;; [35] 誰が使うんでしょうかね、これ...

* 歴史

- [1] [CITE@en[Daring Fireball: Markdown Syntax Documentation]]
( ([TIME[2014-02-05 08:00:15 +09:00]] 版))
<http://daringfireball.net/projects/markdown/syntax>

[2] [CITE[tantek / Markdown]]
( ([TIME[2014-08-30 03:15:04 +09:00]] 版))
<http://tantek.pbworks.com/w/page/59905776/Markdown>

[3] ( ([TIME[2014-11-12 08:09:48 +09:00]] 版))
<http://www.iana.org/assignments/media-types/text/markdown>

[4] [CITE@en[draft-ietf-appsawg-text-markdown-04 - The text/markdown Media Type]]
( ([TIME[2014-12-18 15:13:44 +09:00]] 版))
<http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-04>

[5] [CITE@en[the MDE manifest]]
( ([TIME[2014-11-19 18:20:41 +09:00]] 版))
<http://markdown-extended.github.io/manifest/>

[6] [CITE@en-US[Markdown Community Group]]
( ([TIME[2015-01-02 20:42:23 +09:00]] 版))
<http://www.w3.org/community/markdown/>

[7] [CITE@en[karlcow/markdown-testsuite]]
( ([TIME[2015-01-02 20:43:17 +09:00]] 版))
<https://github.com/karlcow/markdown-testsuite>

[8] [CITE[Markdown Syntax Specification]]
( ([TIME[2015-01-02 20:44:54 +09:00]] 版))
<http://rawgit.com/karlcow/markdown-testsuite/master/markdown-spec.html>

[9] [CITE[The Markdown-Discuss Archives]]
( ([TIME[2014-12-16 13:12:35 +09:00]] 版))
<https://pairlist6.pair.net/pipermail/markdown-discuss/>

[10] [[Pandoc]]

[11] [CITE@en[Comments]]
( ([TIME[2015-02-04 19:42:09 +09:00]] 版))
<http://doc.rust-lang.org/nightly/book/comments.html>


[FIG(quote)[
[FIGCAPTION[
[12] [CITE[Text::Markdown - search.cpan.org]]
([TIME[2015-10-07 17:44:59 +09:00]] 版)
<http://search.cpan.org/~bobtfish/Text-Markdown-1.000031/lib/Text/Markdown.pm>
]FIGCAPTION]

> Markdown is not interpreted in HTML block-level elements, in order for chunks of pasted HTML (e.g. JavaScript widgets, web counters) to not be magically (mis)interpreted. For selective processing of Markdown in some, but not other, HTML block elements, add a markdown attribute to the block element and set its value to 1, on or yes:
>     <div markdown="1" class="navbar">
>     * Home
>     * About
>     * Contact
>     <div>
> The extra markdown attribute will be stripped when generating the output.

]FIG]


[13] [CITE[Markdown - Qiitaマークダウンの癖 - Qiita]]
([TIME[2015-11-13 13:47:15 +09:00]] 版)
<http://qiita.com/Takeru/items/0c5e3f7910498b846bc1>

[15] [CITE@en[RFC 7763 - The text/markdown Media Type]]
([TIME[2016-03-28 02:57:21 +09:00]] 版)
<https://tools.ietf.org/html/rfc7763>

[16] [CITE@en[RFC 7764 - Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations]]
([TIME[2016-03-28 03:11:32 +09:00]] 版)
<https://tools.ietf.org/html/rfc7764>

[24] [CITE[Markdown Variants]] ([TIME[2016-03-29 02:50:58 +09:00]] 版) <https://www.iana.org/assignments/markdown-variants/markdown-variants.xml>

[FIG(quote)[
[FIGCAPTION[
[41] [CITE[Telegram Bot API]]
([TIME[2016-10-03 19:16:17 +09:00]])
<https://core.telegram.org/bots/api#formatting-options>
]FIGCAPTION]

> Use the following syntax in your message:
> *bold text*
> _italic text_
> '''['''text''']'''(http://www.example.com/)
> `inline fixed-width code`
> ```text
> pre-formatted fixed-width code block
> ```

]FIG]


[FIG(quote)[
[FIGCAPTION[
[42] [CITE@en[scholmd/scholmd: Learn how to use scholarly markdown]]
([TIME[2016-11-21 20:13:16 +09:00]])
<https://github.com/scholmd/scholmd>
]FIGCAPTION]

> Markdown is a fantastic and minimalist tool for authoring scientific documents. This repository is a collection of tools, resources, and tutorials to simplfy your workflow. If you spend a little time going through the tutorials you'll be able to stop using Microsoft Word entirely and write clean, lightweight markdown files that can easily be version controlled by git. Collaboration with your coauthors would also become way more powerful and simpler.

]FIG]


[43] [CITE@en[Extending Markdown · scholmd/scholmd Wiki]]
([TIME[2016-11-21 20:14:47 +09:00]])
<https://github.com/scholmd/scholmd/wiki/Extending-Markdown>

[FIG(quote)[
[FIGCAPTION[
[55] [CITE@ja[電書ちゃんのでんでんマークダウン - でんでんマークダウン]]
( ([TIME[2017-04-07 15:00:41 +09:00]]))
<http://conv.denshochan.com/markdown>
]FIGCAPTION]

> HTMLタグのブロックの中でのMarkdownの記述
> PHP Markdown Extra でんでんマークダウン
> 前述したブロックを構成するタグの内部で、Markdown(およびPHP Markdown Extra、でんでんマークダウン)を有効にするには、タグにmarkdown="1"という属性を追加します。この属性は、変換されたHTMLからは取り除かれます。
> 書き方
> これは**通常の段落**です。
> <div markdown="1">
> **ブロックの中の段落**でもMarkdownが解釈されます。
> </div>

]FIG]


[FIG(quote)[
[FIGCAPTION[
[63] [CITE[Markdown をカンニングする方法 - Qiita]]
([TIME[2017-07-03 21:17:16 +09:00]])
<http://qiita.com/akmiyoshi/items/1dc0f2853f499c3bdfd0#comment-7cfd63f74379315d232c>
]FIGCAPTION]

> Qiita 記事 URL 末尾に .md をつける方法は、Google Chrome 等では表示できますが「Content-Type: text/x-markdown」となっているので、IE 等ではダウンロードが開始されてしまいますね。

]FIG]


[FIG(quote)[
[FIGCAPTION[
[64] [CITE[CodeMirror: Markdown mode]]
([TIME[2015-09-02 21:09:56 +09:00]])
<https://codemirror.net/mode/markdown/>
]FIGCAPTION]

> MIME types defined: text/x-markdown.

]FIG]


[66] [CITE@en[mime: please add 'text/x-markdown' for markdown file extensions (md, markdown) to the _defaultExtensionMap · Issue #12857 · dart-lang/sdk]]
([TIME[2017-11-09 02:08:48 +09:00]])
<https://github.com/dart-lang/sdk/issues/12857>

[FIG(quote)[
[FIGCAPTION[
[67] [CITE[Tasks – Flow API Reference]]
([TIME[2017-09-08 02:53:51 +09:00]])
<https://developer.getflow.com/api/#tasks_create-task>
]FIGCAPTION]

> Identify which markup language is used to format the given note
> Supported values:
> text/plain
> text/x-markdown
> text/html

]FIG]


[FIG(quote)[
[FIGCAPTION[
[68] [CITE@en[Markdown | GitHub Developer Guide]]
([TIME[2017-11-09 00:29:22 +09:00]])
<https://developer.github.com/v3/markdown/>
]FIGCAPTION]

>  It takes a Markdown document as plaintext (text/plain or text/x-markdown) and renders it as plain Markdown without a repository context (just like a README.md file is rendered -- this is the simplest way to preview a readme online).

]FIG]


[FIG(quote)[
[FIGCAPTION[
[69] [CITE@en[nkwhr/qiita-markdown-server: A REST API Markdown Server powered by Qiita::Markdown]]
([TIME[2017-11-09 02:17:36 +09:00]])
<https://github.com/nkwhr/qiita-markdown-server>
]FIGCAPTION]

> The raw API is for plaintext (text/plain or text/x-markdown) and renders whole content body.

]FIG]


[FIG(quote)[
[FIGCAPTION[
[70] [CITE@en[Textibility API Documentation]]
([TIME[2017-11-09 02:19:46 +09:00]])
<https://market.mashape.com/ideasynthesis/textibility>
]FIGCAPTION]

> The type of content specified. Can be one of text/plain (plain text), text/html (HTML) or text/x-markdown (Markdown). Markdown will be run through a Markdown processor before the ebook is created, and plain text will be wrapped in an HTML <div> element.

]FIG]


[FIG(quote)[
[FIGCAPTION[
[71] [CITE@en-US[Cognitive Services APIs Reference]]
([TIME[2017-11-09 02:23:21 +09:00]])
<https://westus.dev.cognitive.microsoft.com/docs/services/57cf753a3f9b070c105bd2c1/operations/57cf753a3f9b070868a1f66f>
]FIGCAPTION]

> This method supports raw requests with MIME types listed below:
> • text/html 
> • text/xml 
> • text/markdown 
> • text/plain

]FIG]


[FIG(quote)[
[FIGCAPTION[
[72] [CITE[marked-element documentation]]
([TIME[2017-11-09 02:24:55 +09:00]])
<http://www.cryptomedic.org/bower_components/marked-element/>
]FIGCAPTION]

> Use <script type="text/markdown"> element child to inline markdown
> [SNIP[]]
> Use <script type="text/markdown" src="URL"> element child to specify remote markdown

]FIG]


[FIG(quote)[
[FIGCAPTION[
[73] [CITE@en[Media Types | Reference Material | Akana OAuth API]]
([TIME[2017-11-02 07:33:21 +09:00]])
<http://docs.akana.com/cm/api_oauth/aaref/Ref_MediaTypes.htm>
]FIGCAPTION]

> text/markdown	No	No	
> Indicates that the content is some type of markup; that is, essentially plain text with some formatting instruction syntax included, such as bold, italics, or heading style, to determine how the content is displayed.
> Used in association with certain board items, such as discussions or tickets, to identify whether the board item is in plain text or uses markup to add formatting.

]FIG]


[FIG(quote)[
[FIGCAPTION[
[74] [CITE@ja[開発者向けにMarkdown JPというコミュニティを作ってみました - Islands in the byte stream]]
([TIME[2018-04-18 03:36:31 +09:00]])
<https://gfx.hatenablog.com/entry/2017/10/06/141923>
]FIGCAPTION]

> Markdown自体の仕様については、CommonMarkに期待しているので commonmark.org でよい
> CommonMarkに収まらない拡張を日本語で議論できる場所がほしい
> ルビや数式など

]FIG]


[FIG(quote)[
[FIGCAPTION[
[75] [CITE@en[michelf/mdtest: Test suite for Markdown implementations]]
([TIME[2018-04-19 02:52:55 +09:00]])
<https://github.com/michelf/mdtest/>
]FIGCAPTION]

> MDTest is a Markdown test suite derived from the older MarkdownTest by John Gruber. MDTest is primarily used for the developement of PHP Markdown but is strucutred in a way that can test and benchmark various implementations.
> 

]FIG]