mikeo_410

マークダウンの書き方

 vscode ＋ CodeBraid Preview ＋ CodeBraid ＋ pandoc でマークダウンから .htmlファイルを作ることにしました。
 マークダウン記述で気が付いたことをメモします。

1 markdownlint

 お勧めに markdownlint 拡張機能があったのでインストールして見ました。
 2つのことが分かりました。

1. プレビューのコードブロックの処理中の表示が消えない原因
   プレビューでは下段のステータスバーの「Codebraid」ボタンで、コードブロックの右辺に青いバーが表示され、丸いマークが回転します。
   処理が終われば表示は更新され、この表示は無くなります。
   ところが、これが消えないコードブロックが出来てしましました。
   これは、プレビューだけでなく、pandocでエクスポートした .html にも引き継がれます。
   markdownlint 拡張機能は、コードブロックのスクリプト中のTABコードをワーニングにします。これを無くせば、問題が無くなりました。
2. マークダウンには、HTMLが書けると言う誤解
   そもそも、コードブロックにスクリプトを書いて、table など、HTML を出力して表示できることから始めたことです。
   しかし、markdownlint 拡張機能は、MD033 no-inline-html と警告します。正書法としては、マークダウンに HTMLタグを混ぜないようです。

2 コードブロックのスクリプトの TAB はスペースに置き換える

 プレビューアは、コードブロックの右枠をステータス表示に使っています。css に状態に応じたクラスがあって、オードブロックを表すdiv に設定しています。これは、pandoc で HTMLエクスポートしても保持されます。具体的には、codebraid-output-modified クラスが設定されたままになってしまうことが起きています。
 この現象は、スクリプトに含まれる TABコードをスペースにすれば無くなりました。

3 インライン HTML はワーニング

 インラインのHTMLタグは止められません。リントでワーニングの表示になりますが、やむを得ません。
 HTML のコードブロックに書いたのでは、HTMLとして機能しません。新たな記法が必要なことなのではないかと思います。
 マークアップの大前提は、平文と、機能を持った符号の区別が付くことです。HTMLは <> を機能符号とするので、平文には書くことができません。マークダウンは、同じ文字の繰り返し、あるいはバッククオートで機能符号を識別しています。異なる２つのマークアップが同時に成り立つはずがないのですが、マークダウンは、HTMLのマークアップを簡略に記述する方法と考えれば、少しは納得できます。例えば、文字参照や<br>は必須に思えます。

4 改行と空行

 マークダウン中の改行は、無視されます。pandoc の入力フィルタのオプションに --from reader_lua+hard_line_breaks と書くとマークダウンの行末の改行がプレビューアやエクスポートした文書に反映されます。常に、この状態で使います。
 しかし、改行を複数連続しても、行頭の改行は機能しません。<br> を使うことになります。
 マークダウンのデフォルトは、改行を無視するものですが、空行は意味を持っています。
 行頭にあることが必要な、## や リスト、コード・ブロックの前後は、空行であることが正書法のようです。
 また、HTMLのタグと、マークダウン記述の間も空行で分離される必要があります。
 <br>の前後に空行を置かないと、hard_line_breaks が利かなくなります。

5 divは2重に

 テーブルの文字サイズや、図の配置のために、divタグを書きますが、2重に囲む必要があります。

<div style="font-size:9pt">
<div>

|A|B|
|--|--|
|あ|い|

</div>
</div>

 プレビュー時だけの問題です。テーブルの前の記述は、<div data-wrapper="1">で囲まれます。
<div data-wrapper="1"> <div style="font-size:9pt"> </div> <table>・・・
と、なって機能しません。もう一つ divタグを書くと上手くいきます。
<div data-wrapper="1"> <div style="font-size:9pt"> <div> </div> <table>・・・
 しかし、テーブルの前のコンテンツを囲んでいた <div data-wrapper="1"> がテーブルも包含することになって、同じではありません。<div data-wrapper="1"> はプレビューに必要なものだと思いますが、付加している箇所が分かれば、HTMLタグには付加しないようにしたいところです。

6 バッククォートの扱い

 マークダウンでは、バッククオートがコード・ブロックを示します。
 マークダウン記述を説明するには、バッククオートが表示され、コード・ブロックとは見なされない記法が必要です。
 決定的な方法は見つかりませんが、以下の方法は可能です。

1. コード・ブロックを作る、バッククオート3つの囲みは、show オプションで表示できる。

   ```{.R .cb-nb show=markup+stdout}
   str(pi)
   ```

    num 3.14

2. チルダ ~ は、バッククオートの変わりで、相互に、囲んだ内側では機能を失わせて表示することが出来ます。
3. チルダやバッククオートは、連続した2つで囲む方法があって、同じ記号を機能を失わせて表示します。

7 貼り付けると化ける

 まだ、問題が特定できていませんが、規則性のありそうな化け方をします。たいてい、コード・ブロックには、他のエディタからカット＆ペーストをします。
 コード・ブロックを実行する場合は気が付きますが、Visual Studio から C# のコードを、表示だけが目的で貼った個所は注意が必要です。かなりの割合で文字が抜けています。