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

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

代替

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

仕様書

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

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

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

[81] CommonMark も中核部分を「共通」の「標準」 として記述することが目標で、 言語の統一を目指しているものではなさそうです。 CommonMark を採用した上で、 構文の拡張や変更ができることを売りにした実装がある >>80 (しかも実際に採用されて拡張された例がある) ことからもわかるように、 Markdown コミュニティーには統一言語確立のモチベーションよりも独自拡張を好む風習があるようです。

方言

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

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

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

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

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

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

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

[83] MFM (Markup language For Misskey) は 「Misskeyで使えるMarkdown風の構文」 と説明されていて、 Markdown であるとは主張していません。 実際、独自性が強いです。

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

[94] Markdown Flavors · commonmark/commonmark-spec Wiki · GitHub, https://github.com/commonmark/commonmark-spec/wiki/Markdown-Flavors

[95] Deployed Extensions · commonmark/commonmark-spec Wiki · GitHub, https://github.com/commonmark/commonmark-spec/wiki/Deployed-Extensions

[97] PHP Markdown Extra, , https://michelf.ca/projects/php-markdown/extra/

[96] GitHub - vmg/redcarpet: The safe Markdown parser, reloaded., https://github.com/vmg/redcarpet

構文

[40]

HTML との混用

[88] CommonMark を含む多くの Markdown の方言は、 Markdown 文中に HTMLタグを記述可能としています。 HTMLタグは、 HTMLタグが生成されるべきことを表します。 そのまま素通しで出力する実装もあるでしょうし、 何らかの加工をして出力する実装もあることでしょう。

[89] Markdown における HTMLタグは、 HTML 本来のタグとは仕様が異なることがあります。 タグ構文がHTML構文解析器と違った形で解釈されますし、 HTML にない独自の属性が利用可能な場合もあります。

[90] HTMLタグに囲まれた部分が Markdown として解釈されるかどうかは実装によります。

[91] 利用可能なHTMLタグの種類は実装によります。

[92] HTML に Markdown を含めることはできません。 script data block のような形で Markdown データを含めることはできますが、 それはあくまで文書が何らかの独自の形で使い得るデータとして含めているものに過ぎず、 HTML が表す文書構造の一部分の記述の手段として Markdown を利用することはできません。

[93] HTML をモデルに開発された構文HTMLもどきや HTML を生成することを目的とした言語のようなものの中には、 HTML に基づく構造を全体構造とし、 その一部分に Markdown に基づく構造の利用を認めていることがあります。

MIME型

[22] IETF は RFC 7763 でMIME型 text/markdown を規定しています >>15。

variant 引数

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

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

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

charset 引数

[26] charset 引数があり、必須とされています >>15。

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

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

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

その他の引数

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

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

text/x-markdown

[60] MIME型 text/x-markdown が使われることもあります。 text/markdown より前から使われていました。

[86] 新しい実装は text/markdown を使うべきで、 text/x-markdown を生成するべきではありません。

[87] 実装は text/x-markdown も text/x-markdown も等価として認識するべきです。

[61] Beta API docs · CPAN-API/cpan-api Wiki ( ( 版)) https://github.com/CPAN-API/cpan-api/wiki/Beta-API-docs

[62] はてなブログAtomPub - Hatena Developer Center ( 版) http://developer.hatena.ne.jp/ja/documents/blog/apis/atom

contentにははてなブログに登録されたシンタックスと解釈されたオリジナルな文面が記載されます

type属性には以下の3つの値のいずれかが付与されます。

text/html 見たままモード

text/x-hatena-syntax はてな記法

text/x-markdown マークダウン記法

[48] Markdown | GitHub Developer Guide ( ()) https://developer.github.com/v3/markdown/

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).

素片識別子

[30] RFC 7763 は、 text/markdown における素片識別子は方言次第としつつ、独自の構文も定めています >>15。

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

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

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

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

API

[14] Markdown API。

互換性と相互運用性

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

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

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

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

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

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

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

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

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

文脈

[98] Data Package >>82

[99] llms.txt

[82] Data Package | Frictionless Standards, , https://specs.frictionlessdata.io/data-package/#metadata

The description MUST be markdownリンクhttp://commonmark.org/ (opens new window) formatted – this also allows for simple plain text as plain text is itself valid markdown.

関連

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

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

歴史

[2] tantek / Markdown ( ( 版)) http://tantek.pbworks.com/w/page/59905776/Markdown

[3] ( ( 版)) http://www.iana.org/assignments/media-types/text/markdown

[4] draft-ietf-appsawg-text-markdown-04 - The text/markdown Media Type ( ( 版)) http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-04

[5] the MDE manifest ( ( 版)) http://markdown-extended.github.io/manifest/

[6] Markdown Community Group ( ( 版)) http://www.w3.org/community/markdown/

[7] karlcow/markdown-testsuite ( ( 版)) https://github.com/karlcow/markdown-testsuite

[8] Markdown Syntax Specification ( ( 版)) http://rawgit.com/karlcow/markdown-testsuite/master/markdown-spec.html

[9] The Markdown-Discuss Archives ( ( 版)) https://pairlist6.pair.net/pipermail/markdown-discuss/

[10] Pandoc

[11] Comments ( ( 版)) http://doc.rust-lang.org/nightly/book/comments.html

[12] Text::Markdown - search.cpan.org ( 版) http://search.cpan.org/~bobtfish/Text-Markdown-1.000031/lib/Text/Markdown.pm

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.

[13] Markdown - Qiitaマークダウンの癖 - Qiita ( 版) http://qiita.com/Takeru/items/0c5e3f7910498b846bc1

[15] RFC 7763 - The text/markdown Media Type ( 版) https://tools.ietf.org/html/rfc7763

[16] RFC 7764 - Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations ( 版) https://tools.ietf.org/html/rfc7764

[24] Markdown Variants ( 版) https://www.iana.org/assignments/markdown-variants/markdown-variants.xml

[41] Telegram Bot API () https://core.telegram.org/bots/api#formatting-options

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

```

[42] scholmd/scholmd: Learn how to use scholarly markdown () https://github.com/scholmd/scholmd

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.

[43] Extending Markdown · scholmd/scholmd Wiki () https://github.com/scholmd/scholmd/wiki/Extending-Markdown

[55] 電書ちゃんのでんでんマークダウン - でんでんマークダウン ( ()) http://conv.denshochan.com/markdown

HTMLタグのブロックの中でのMarkdownの記述

PHP Markdown Extra でんでんマークダウン

前述したブロックを構成するタグの内部で、Markdown(およびPHP Markdown Extra、でんでんマークダウン)を有効にするには、タグにmarkdown="1"という属性を追加します。この属性は、変換されたHTMLからは取り除かれます。

書き方

これは**通常の段落**です。

<div markdown="1">

**ブロックの中の段落**でもMarkdownが解釈されます。

</div>

[63] Markdown をカンニングする方法 - Qiita () http://qiita.com/akmiyoshi/items/1dc0f2853f499c3bdfd0#comment-7cfd63f74379315d232c

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

[64] CodeMirror: Markdown mode () https://codemirror.net/mode/markdown/

MIME types defined: text/x-markdown.

[66] mime: please add 'text/x-markdown' for markdown file extensions (md, markdown) to the _defaultExtensionMap · Issue #12857 · dart-lang/sdk () https://github.com/dart-lang/sdk/issues/12857

[67] Tasks – Flow API Reference () https://developer.getflow.com/api/#tasks_create-task

Identify which markup language is used to format the given note

Supported values:

text/plain

text/x-markdown

text/html

[68] Markdown | GitHub Developer Guide () https://developer.github.com/v3/markdown/

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).

[69] nkwhr/qiita-markdown-server: A REST API Markdown Server powered by Qiita::Markdown () https://github.com/nkwhr/qiita-markdown-server

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

[70] Textibility API Documentation () https://market.mashape.com/ideasynthesis/textibility

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.

[71] Cognitive Services APIs Reference () https://westus.dev.cognitive.microsoft.com/docs/services/57cf753a3f9b070c105bd2c1/operations/57cf753a3f9b070868a1f66f

This method supports raw requests with MIME types listed below:

• text/html

• text/xml

• text/markdown

• text/plain

[72] marked-element documentation () http://www.cryptomedic.org/bower_components/marked-element/

Use <script type="text/markdown"> element child to inline markdown

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

[73] Media Types | Reference Material | Akana OAuth API () http://docs.akana.com/cm/api_oauth/aaref/Ref_MediaTypes.htm

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.

[74] 開発者向けにMarkdown JPというコミュニティを作ってみました - Islands in the byte stream () https://gfx.hatenablog.com/entry/2017/10/06/141923

Markdown自体の仕様については、CommonMarkに期待しているので commonmark.org でよい

CommonMarkに収まらない拡張を日本語で議論できる場所がほしい

ルビや数式など

[75] michelf/mdtest: Test suite for Markdown implementations () https://github.com/michelf/mdtest/

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.

[79] Producing HTML, , http://sgmljs.net/docs/producing-html-tutorial/producing-html-tutorial.html#parsing-markdown

[80] markdown-it/markdown-it: Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed () https://github.com/markdown-it/markdown-it

Markdown parser done right. Fast and easy to extend.

Follows the CommonMark spec + adds syntax extensions & sugar (URL autolinking, typographer).

Configurable syntax! You can add new rules and even replace existing ones.

[84] 2024-07-07 togetterのMarkdown記法ではH3 H4 H5…見出しは使えるか実験 - Togetter [トゥギャッター] () https://togetter.com/li/2397177

[85] >>84 Hn と書いているが実際にはMarkdownの見出し構文のこと。 実際に出力されている HTML によると、 # は h2, ## は h3, ### から ###### は span (以上すべて少しずつ CSS が違う)、 ####### は Markdown 構文として解釈されずそのまま出力。

[100] markdownはデカイ文字を書くのに便利 - 橋本商会, https://scrapbox.io/shokai/markdown%E3%81%AF%E3%83%87%E3%82%AB%E3%82%A4%E6%96%87%E5%AD%97%E3%82%92%E6%9B%B8%E3%81%8F%E3%81%AE%E3%81%AB%E4%BE%BF%E5%88%A9

[101] なぜ強調表示できず ** が表示されるのか — Perlで始まったMarkdownの歴史と日本語文書における課題 - Speaker Deck, https://speakerdeck.com/kwahiro/nazeqiang-diao-biao-shi-dekizu-star-star-gabiao-shi-sarerunoka-perldeshi-matutamarkdownnoli-shi-tori-ben-yu-wen-shu-niokeruke-ti