Markdown対応†
- ページ: BugTrack
- 投稿者: umorigu
- 優先順位: 低
- 状態: 提案
- カテゴリー: 本体新機能
- 投稿日: 2017-01-06 (金) 03:10:07
- バージョン: 1.5.1
メッセージ†
技術系の簡易マークアップ記法としてはMarkdownがデファクトスタンダードになっている。
PukiWikiの他の機能は維持したまま、Wiki記法としてMarkdownを使いたい。
課題・懸念点†
- 1. PukiWiki文法とMarkdownを選択する必要がある。ユーザーから見た複雑さの増加
- 2. 実装の複雑化、これによるバグの増加
- 3. PukiWiki文法を前提としているプラグインとの整合性
- 4. プラグイン書式（インライン要素/ブロック要素）
考察 by umorigu (2022/1-)†
- PukiWiki文法 - Markdown のサイト単位の切り替えだと、他に比べてPukiWikiを選ぶ理由が弱い。少なくともページ単位での切り替えは必要 (既存のPukiWikiサイトでMarkdownが使える、という形)
- PukiWiki文法を使うユースケースに影響がないようにしたい
- JavaScriptが使えるのは前提でよい
- 外部ライブラリ (Markdownパーサー) にどの程度依存するか？
- HTMLタグの扱いをどうするか
- Wikiを書きたい人が積極的にHTML直接入力を求めているとは思えない。自由入力はなしでいいのでは？
- CommonMarkでサポートしていない表組みをどうするか？
- GFM (GitHub Flavored Markdown) 風にするのが良いか？
- そもそも複雑なことは求められていなく、 見出し、リスト、単一行文字修飾、程度が動作すればよいかもしれない
- 「プラグインを一切サポートしない」はPukiWiki標準機能としてありか？なしか？
大きな課題はプラグイン
- 他のMarkdown採用のWikiやそれに類するソフトウェアがMarkdown中で「プラグイン」や「マクロ」をどのような文法で実現しているか？
- Calendar のように、別のページを取り込むプラグインに対してどう対処するか
- PukiWiki文法しか解釈しないユーザープラグインをどうするか (プラグインの文法依存があるか？)
実現方法の選択肢をいくつか
- 1 PukiWiki文法のようにMarkdownを解釈する
- 1.1. 自力でパーサーを作る
- 1.2. 外部ライブラリを利用する
- 2 すべてテキストとして扱い、HTML出力までそのまま。パースと修飾をすべてJavaScriptで行う
- 3 Markdownテキスト を PukiWikiテキストに直接変換し、パースと修飾はPukiWikiテキストに対して行う
- Markdown では意味がなく PukiWikiでのみ意味がある書き方を検出してエスケープする必要がある
- プラグインが読み込むときはPukiWikiテキストになっているとプラグイン側での対応が不要になる
Markdown として認識されるために必要な要素†
- 見出し (# 始まり) 1,2,3,4
- ( ==== や ---- は無くても許されるのでは・・・ )
- CommonMark では見出しは # の後にスペースが必要
- 強調: * または _ で囲む
- リスト: 行頭に * または -
- サブリスト (インデント): スペース2つ + -
- 番号付きリスト: 行頭に 数字. 1. 2. 3.
- 引用: 行頭に >
- ソースコード: ` バッククォートで囲む
- 区切り線 *** または ___ または ---
- 表組み・テーブル ( GitHub Flavored Markdown )
- 画像: 行頭に !
- img タグ？ (size 指定などは imgタグでないとできない)
- リンク [タイトル](リンク先URL)
MarkdownであってもPukiWikiとして組み込みたい機能†
PukiWiki機能のうち、Markdownでは不要/あるいは動いては困る機能†
Markdownとして書いているのに、PukiWiki的な文字修飾が動作するとマズイ
- PukiWikiの文字修飾機能: 太字・協調
- 見出し: *始まり
- リスト: -始まり
プラグインの対応†
- 理想的には、各プラグインがMarkdownのことを知らなくても、それなりに動作すること
- そんなことが可能？
- Markdown → PukiWiki, PukiWiki → Markdown が情報欠損なく変換できれば理論的にはできる
- 一般的には無理なので、ある一定の文法範囲だけMarkdownは動作する、ということにする？
- 次点で、Markdownのことを知っているプラグインは、Markdownページで使える、ということにする
- 一番簡単なのは、「ページをMarkdownで書く際には自己書き換え型プラグインは一切動作しない」ということにする
- どうやってそのルールを適用するか？ (Markdown非対応のxxcommentプラグインがMarkdownページを書き換えないようにするか？) または 「AS-IS で動くように動く」「使わないでください」 という依頼のみにする
- 自己書き換え型プラグインとは？ (comment, pcomment →使用頻度が高いので厳しい)
- 書式のコンフリクトが深刻です。「Markdownの場合はプラグインの利用不可」としてもある程度は有用なのではないかと思っています。calendarの日単位の記事がMarkdownになるイメージ -- umorigu
- 記法をさらに一段抽象化して、「情報の構造/階層」と「そのデザイン」に分離する様に取り組まないと、プラグインインジェクションないしwiki text injection とでも言うべき脆弱性を作りこんでしまうかもしれませんね (^^; -- henoheno
- devneko: Pukiwikiを無理やりMarkdown記法に変えてみた ://qiita.com/devneko/items/fafac4ade37c9cb3d2f4 ://github.com/dotneet/pukiwiki-md --
- 拡張子を見てrendererを切り替えるような実装が望ましいかなあと -- n1x
- ブログ書くなら Pukiwiki記法 か Markdown記法 か (WordPressの場合) ://tande.jp/lab/2012/07/1838 --
- PukiwikiでMarkdown記法を使う (PKWKEXP_DISABLE_MULTILINE_PLUGIN_HACKで、部分的に) ://blankrune.hateblo.jp/entry/2014/01/27/233945 --
- pukiwiki-plugin/plugin/markdown.inc.php ://github.com/sonots/pukiwiki-plugin/blob/master/plugin/markdown.inc.php --
- official:自作プラグイン/markdown.inc.php --
- markdown.inc.phpは現状でPHP 8.0未対応で、これを使っているページはPHPエラーで真っ白になって表示できません。 -- -
- Markdown文法の「改行」末尾に空白２つは、見た目もわからないし生理的に受け付けない -- kintok
- 「改行」末尾に空白２つ、は最近のMarkdownの『方言』では不要になってきています。 -- m0370
- markdown.inc.phpを入れた時に動かなくなるプラグインのリストはあるのでしょうか？なんとなくレンダリングに関係するプラグインはダメで、そうでないものは大丈夫なことが多い気はしていますが。。 -- medst
- 将来も持続的に発展してゆくためには、やはりPukiwiki記法にこだわらずmarkdown記法を取り込んでゆく必要があるように思いますね。markdown記法はユーザー数が圧倒的に多いですからPukiwikiコミュニティも非常に盛り上がるはず。pukiwiki.ini.phpに define('PKWK_SAFE_MODE', 1); のような設定項目を作って記法をスイッチできるようになれば理想ですが。 -- -
- 全体設定で文法を切り替えることにするというのはPukiWiki文法は使えずにMarkdownだけ使えることになりますかね。そうだとするとMarkdownを採用する他のWikiソフトウェアに比べてPukiWikiを選択する理由があまりないので理想とも言えないんですよね。導入するなら共存しかないのかなと思います -- umorigu
- 全体設定ではなく、ページ毎にPukiwiki記法とMarkdown記法を使い分けられるようにしてみました。https:// oncologynote.com/?ae42d4ca0c github.com:m0370/pukiwiki153_md -- m0370
- Pukiwiki記法のページはそのままに、編集画面でMarkdownのチェックボックスをオンにして記事を確定すると本文に#notemdの文字を書き込むようにしています。そして、#notemdがある記事はPukiwiki記法のparserではなくMarkdown parserに記事を渡します。Pukiwiki記法で書いたページには触らないので既に稼働しているPukiwikiからの引越もしやすいかと思います。Markdown記法の場合はフリーのjavascriptを読み込むだけで書式のリアルタイムプレビューも可能です。なお、プレビュー機能、複数行プラグインに未対応です。 -- m0370
- なお、MarkdownはHTMLをそのまま投入できるので誰でも自由に書き込めるPukiwikiの場合はクロスサイトスクリプティングのような脆弱性の問題があります。今回の改造ではerusev/markdownのMarkdown parserを使っていて、このparserにはセーフモードにする（あるいはHTMLは全てエスケープする）という設定項目もあり、pukiwiki.ini.phpでこれを有効にすることができるようにしていますが、セーフモードにすると表記したもののうちリンクを含む部分はコードが変換されずそのままむき出しになるので見栄えがわるいです。 -- m0370
- Markdown対応の実装ありがとうございます。非常に興味深いです。ご指摘のようにMarkdownはその特徴としてHTMLタグをそのまま書けるので、htmlinsertと同じような対処が必要になりそうです。blogのように第三者に編集をさせない用途があるのはわかってはいるのですが、Wikiとしての利用((限定されていたとしても)複数人から編集され内容は必ずしも安全でない)を優先した仕様であるべきと考えています -- umorigu
- SimpleMDEでのリアルタイムプレビューはとてもよいですね -- umorigu
- github.com:m0370/pukiwiki153_md/commit/e6a5fd7bc03d1f8fab0cdf9eaed5852505d582e ここのコミットからpukiwiki.ini.phpでsafemodeを設定できるようにして、Pukiwiki記法で書いたときと同じmake_link.phpのhtmlsc($string)に渡すようにしたので、pukiwiki.ini.phpでsafemodeを有効にしている場合はHTMLタグのspecialcharactersはおそらくPukiwiki記法で書いた場合と同じ程度には無害化されていると思います。MULTILINEプラグイン対応はいま取り組んでいますが、まだ解決していません。 -- m0370
- m0370 さんの pukiwiki153_md の変化点がわかりやすいようにまとめなおしました。 github.com:umorigu/pukiwiki153_md/pull/2 変更は意図通りでしょうか？ これを見ると、commentやvote等、自己書き換え型のプラグインはすべて本文がMarkdownで書かれていることを知っている必要がありますね(なにか対策ができるか、そういうものとして全プラグインを対応させるか) -- umorigu
- Pukiwiki 1.5.4のPukiwiki記法とMarkdown記法対応版も作ってみました。例によって複数行プラグインの対応させ方がわからず、複数行プラグインは使用できません。github.com:m0370/pukiwiki154_md/releases/tag/v0.1 https:// oncologynote.com/?baa57eda56 -- m0370
- Markdown実装ありがとうございます。参考になります。外部ライブラリを使うかどうかと、既存プラグインとの互換性が課題だなと思っています -- umorigu
- この件、なかなか進まないのはMarkdownパーサーをPukiWiki本体に組み込もうとしているためではないでしょうか？ プラグインのように、パーサーのインターフェイスだけを定義しておき、実装と責任はPukiWiki本体から分離するほうが良いかと。それならMarkdown以外の記法にも対応できますし、本体とは独立したサイクルでパーサー開発を進められます。同梱外部ライブラリにライセンスを合わせることもできます。
で、パーサーには「対応記法・名前空間URI等のID・バージョン・ページファイル拡張子」といった識別情報を提供させ、ページを編集するときに選べるのはもちろん、記法に依存するプラグインにはその識別情報を見て動作を変えさせるようにします（※）。
※ ページの相互変換や抽象化により既存プラグインとの透過的な互換性を実現するのは、理想的ではありますが次の理由で現実的ではないと思います。
1) PukiWiki記法と他記法との1対1の互換性は期待できない
2) 互換性を優先して他記法側を制限すると、結局使いにくいものになりかねない（使いたかった記法が使えない・特殊な方言として覚えねばならない・表現力が広がらない）
3) 変換の負荷がいちいち余計にかかる
ただし、パーサー側にPukiWiki記法との相互変換インターフェイスを用意しておき、もし可能であれば実装させる、という運用はありかもしれません。
なお、新たな記法を用いて新規ページにプラグインを埋め込む際には、それがまともに動作するかはほぼその時点でわかるため、互換性の問題は生じないはずです（このプラグインは使えないのだな、と割り切ってもらうだけ。現時点でもPukiWiki本体やPHPのバージョン違いで使えないプラグインなどざらなのだから、そう面食らうことではない）。また、対応プラグインのホワイトリスト／ブラックリストをパーサーから取得できるようにすれば、非対応のプラグインは使われていても無視する・編集時に警告を出すといった安全策もとれると思います（少なくともメジャーなものに対しては）。
こうした仕組みにした場合、記法に依存するプラグインに記法（パーサー）の数だけ異なる処理を加えていくのは大変では？との懸念については、事実上そのコストは限定的だと思います。今日のPukiWiki周辺の開発状況を見るに、無数の作者によってパーサーが乱立するとは考えにくいためです。リファレンスとなる公式のMarkdownパーサーをひとつ用意し、commentなどの標準プラグインもそれにだけ対応させておけば当面十分でしょう。パーサーがオマケである以上それとて義務ではありませんし、徐々に対応させる方針でもかまいません。 -- mt
- ご意見ありがとうございます。「プラグインのように、パーサーのインターフェイスだけを定義しておき、実装と責任はPukiWiki本体から分離するほうが良いかと。それならMarkdown以外の記法にも対応できますし、本体とは独立したサイクルでパーサー開発を進められます。」→こういう方針も可能性としてはアリですが、問題は現実の設計と実装がどうなるかですね。複数の実装が出てきて「本体として組み込むのはどれがよいか？」というのを議論できるのが理想ではあります。Markdownプラグインやm0370さんらのカスタマイズ実装はすでにありますし、個々の利用者がこれを取り込んで利用することは今でもできます。Markdownが最優先であれば最初からCrowiやGrowiのようなPukiWikiでないMarkdown Wikiソリューションを選ぶこともできます。PukiWikiの特徴である、設置の簡便さを損なわない形、さらに現行PukiWiki利用者が十分受け入れられるものでないと、ごく限定された利用しかされず、それであれば現在と同じく個別カスタマイズで十分、ということにもなりかねません。（本体で提供する意味がなくなってしまう） -- umorigu
- 確かに、今のところ限定的なMarkdown書式だけサポートしてPukiWiki本体にロジックをすべて組み込み(外部ライブラリを使わない)が良いかなと思っています。HTMLタグは基本、利用できないと思っています。 (htmlプラグインの利用に制限をかける必要があるのと同じ理由です。互換性も高い方がよいのですが、難しいところですね。m0390さん版のバランスはかなり良い方だとは思います。 -- umorigu
- この件の最大のボトルネックは、技術的なことよりも（現にプラグインや本体改造例が出ているようにやりようはある）、具体的な需要のほどがわからないこととお見受けしています。ご説明にある、一握りの人しか使わないのなら個別に改造すればいいし、Markdownだけ使いたいなら他のウィキを使えばいいし、という迷いがまさにそうだと思うのです。具体的な仕様について、一般的には安全優先で制限をかけるべきだがどうしよう、というのもしかり。そこで立ち往生しているように見えたため、先の提案をさせていただきました。
つまりPukiWiki本体には枠組みだけを作っておき、あとは好きにせい、と需要に応える仕様作りと責任とを外部のパーサーに委ねてしまったほうが状況が前に進むのでは、という提案です。これは責任放棄ということではなく、Markdownを真剣に求める人たちがそこに集中することで、パーサーや周辺プラグインの実装はむしろ洗練されていくのでは、と期待しているのです。実際、m0370さんのような方がいらっしゃるわけで。それが個別の本体改造ということになると、せっかくの実装が複雑な手順を要するマイナーなものに終わりかねない、と危惧しています。 -- mt
- Markdown対応を本体に組み込もうという方針には疑問があります。新規に開発されるウィキシステムが、現在最も普及しているMarkdownを唯一の記法として採用するのならわかります（現今のウィキはそうですね）。が、求められる記法の変化を長年のあいだに経験し、それにせっかく記法選択式という形で応えようというPukiWikiが、しかし他の需要や将来の変化の可能性には対応しない（再び本体改修するしかない）、というのは率直に言って場当たり的かつ矛盾した方針に思えます。また、ここまで言っておいて何ですが、私自身はPukiWiki記法で間に合っているため、使いもしない他記法対応で本体が肥大化・複雑化したりバグが増えたりするのも避けたく。それでも、他記法の導入によりPukiWikiが活気づくのなら結局はユーザーである自分の得にもなるわけで、そこで先の理由もあり、外部パーサー方式はどうだろうと考えました。 -- mt
- Markdown対応の需要はかなりあると思っていて、私も欲しいです。表現の違いだけかもしれないですが「PukiWiki本体には枠組みだけを作っておき、あとは好きにせい」を技術的にどう実現するのか、というのが難しいところなのかと思っています。別の書き方をすると、「もっといい設計/仕組み/実装がないかな？」ということです -- umorigu
- 言いたい放題で少々後ろめたくなったため、ざっくりではありますが複数の記法に対応するパーサー分離の「枠組み」、プラグイン型パーサーを作ってみました。m0370さんの改造をプラグイン化してみた感じで、コードをかなり流用させていただいています。あくまで仕組みを例示するための試作であり、最低限の定義・実装しかしておらず、細かな不具合は放置しています。 github.com:ikamonster/pukiwiki-parser-prototype （追記：非公開になっていたので公開に直しました）-- mt
- プロトタイプ実装をありがとうございます。できれば(リポジトリ内での) Pull Request の形で、m0370さんの実装やPukiWikiオリジナルからの差分がわかるようになっていると助かります。例えば github.com:umorigu/pukiwiki153_md/pull/2 のような形です。 -- umorigu
- プルリクエストではありませんが、PukiWikiオリジナルとの差分がわかるようにしてみました。 github.com:ikamonster/pukiwiki-parser-prototype/compare/original...main?diff=split -- mt
- ありがとうございます。大変参考になります。パーサー実装は本体側で切り替えられるようにして、一方プラグインがどの「パーサー実装」に対応するかは各プラグインの実装に任せる形ですね。やはりプラグインの対応をどういう方向に割り切るかというのがポイントになりますね。 -- umorigu
- 「Markdown対応を本体に組み込もうという方針には疑問」「他の需要や将来の変化の可能性には対応しない（再び本体改修するしかない）、というのは率直に言って場当たり的かつ矛盾した方針に思えます。」→ここについては少し異なる意見を持っていて、Markdownはこの20年(のさらに前半10年かも)でデファクトスタンダードになったのだから、追加サポートはMarkdownだけでよいだろうと考えています。一般に汎用性と個別最適化は相反し、さらに他の記法もサポートしようとするとMarkdown利用時のUXの質は落ちてしまいます。もちろん「汎用的に対応できて個々の使い勝手も十分に良い」設計ができればそれが一番です。問題はそれが可能かどうかで、現実の実装がすべてです。というわけで10年後に別の記法が流行ったらそのときに対応しましょう。 -- umorigu
- 一理ありますね。ただ繰り返しになりますが（そして論点がちょっとずれてしまうかもしれませんが）、私見ではそうした技術的な問題よりも、新たなデファクト記法を本体に組み込むがゆえの慎重さによる膠着状態がこの件の最大の障害だと思っています。5年前に起草されていまだ（公式には）実現していないのでは、UXや実装以前の問題と言わざるを得ません。次に別の記法が流行したら、それを取り込むのにもまた何年もかかるのではないか。主観的な設計思想のこともありますが、それ以上にこの膠着状態を解消する手立て、つまり目下のMarkdownパーサーを唯一決定的な実装と重く考えずに済み、かつ本体から切り離す方法としての汎化・外部化方針を推すための、あの主張は方便であったのが本当のところです。また、範囲と質とが相反するというのは、リソースが限られた条件での話ではないでしょうか。ならば、その問題もやはり開発を外部化することで解消ないし軽減される可能性があります。一方で、PukiWiki本体がMarkdownを内部に持ち、公式の仕様を定めることでユーザーも開発者も安心してそれを使うことができる、その意味で総合的なUXが向上するのは確かにおっしゃる通りです。
設計の話に戻ると、私はMarkdownは日常使わないものの、ウィキペディア（MediaWiki）記法がもし使えたらうれしいなとはちょっと思っていました。また、むろん個人用途に限りますが、HTMLを素で書けるパーサー（ほぼ素通し）が欲しいなとか。どちらも需要は少ないでしょうが、こうしたことが念頭にあり、せっかく改修するなら汎用にすればいいのに、と考えたのでした。それと、PukiWiki本体はできるだけ単純・軽量であって欲しいなとも。しかしいずれにせよ前にも書いたとおり、汎用化したところで現実には単一のMarkdownパーサーしか使われない・作られないだろうと思っています。
プラグインの互換性の問題についても前に書いたとおりで、PukiWiki記法と他記法との相互変換は難しいため、記法ごとにプラグイン側が対応するしかなかろうという考えです。それでも、PukiWiki記法で書かれた既存のページには影響ないのだし、対応すべきは事実上Markdownだけなのだからいいじゃないか、と割り切る。として前に進むと、その各プラグインのMarkdown対応を、いかに開発者にとって作りやすく、ユーザーにとってわかりやすく導入しやすくするか、が次の課題になります。
その答えには、いわゆるMOD方式が良いのでは、と考えています。たとえば、Markdownパーサー用のプラグインディレクトリを堀り、そこに既存プラグインのMarkdown対応版を、既存プラグインファイルと同名で配置する（例：parser/markdown/plugin/comment.inc.php）。Markdownページを表示中にプラグインを呼び出す際は、標準プラグインディレクトリにあるのと同名のプラグインファイルがMarkdown用プラグインディレクトリ内にあればそちらを優先して呼び出す（なければ標準プラグインディレクトリから呼び出す）、という仕組みです。これなら元のプラグインファイルをいじる必要はありませんし、パーサーに対応するプラグインの有無が一目瞭然です。 -- mt
- MOD方式で各パーサー用プラグインを優先実行する仕組みを実装してみました。ファイル構成が少々変わったのでご注意ください。 github.com:ikamonster/pukiwiki-parser-prototype -- mt
- 「#」の扱い。見出しについて、オリジナルの Markdown だとどうしようもないのですが、 CommonMark ( https:// spec.commonmark.org/0.30/ ) の場合、見出しにするためには「#」の後にスペースが要求されます ( スペースなしの #tag のような表記は見出しとせず、ハッシュタグ等を表現可能にしている )。これを利用すると、「# の後スペースがあれば見出し」 「# の後スペースがなければブロックプラグイン呼び出し」 という切り替えができそうです。CommonMarkがどのぐらい普及しているのかわからないですが、GitHubはすでにCommonMark準拠になっていましたし問題ないでしょう。 -- umorigu
- プラグイン呼び出しのための記号が「#」で統一できれば、Markdown（および他記法）への対応はかなり簡単にできるかと思います。具体的には、Pukiwiki記法処理のほとんどの処理が lib/html_convert.php と lib/make_link.php で行われているので、この部分の切替だけで可能になりそうに思います。edit.inc.php などは本来libフォルダに入っていそうなものがプラグインとして組み込まれているので、同じようにlib/html_convert.php や lib/make_link.phpをhtml_convert.inc.php や make_link.inc.php のようにプラグイン化することは実現可能かと思います。 -- m0370
- Markdownパーサーが変換に利用している「Parsedown」クラスの"#"ブロック判定メソッドをオーバーライドし、"#"の後の空白を必須とするようにしてみました（追記：そしてプラグインは「#hoge」で呼べるようにし、複数行プラグインにも対応しました。また、編集ヘルパーに対応しました）。 github.com:ikamonster/pukiwiki-parser-prototype
CommonMark対応PHPライブラリとしては「league/commonmark」がメジャーなようですが、依存関係など大きくて導入が面倒ですね。開発者ならともかく、一般ユーザーにこれをcomposerインストールせよというのは…。ParsedownもいちおうCommonMark対応という触れ込みではありますが、この#ブロックの件のように厳密ではないようです。 -- mt
![[PukiWiki]](image/pukiwiki-dev.png "[PukiWiki]")
