Moodle の Markdown を理解したい

Re: Moodle の Markdown を理解したい

- ya ra の投稿
返信数: 0

PHP Markdown Extra

まず、PHP Markdown Extra についてざっと確認します。

PHP Markdown Extra は以下のサイトで Markdown 記法が紹介されています。

https://michelf.ca/projects/php-markdown/extra/

PHP Markdown Extra の仕様は、基本的に John Gruber's Markdown を拡張する形で決められています。

これを踏まえて、概要としては次のように列挙できます。

  • John Gruber's Markdown からの変更点：
    • HTML ブロックに対してより緩い制限
    • HTML 内に Markdown を含める場合は markdown="1" 属性を指定する
    • 参照定義リンクの参照部分では、collapse 型に対応しない
    • _ による強調は、左右が文字に当たっていると強調にならない (e.g. secret_magic_box)
    • 1. 以外の数字から始めた番号付きリストは、その数字から始まる
    • 表と定義リストの追加に伴って |、: に \ を課すことでエスケープできる
  • 追加された記法：
    • 属性の追加
      • 見出し
      • Fenced code block
      • リンク
      • 画像
    • 表
      • 揃え位置の調整あり
    • 略称
    • 定義リスト
    • 脚注

表と略称は Leaf blocks、定義リストと脚注は Container blocks です。

また、Container blocks に他の Container blocks を挿入する場合は the four-space rule に従って挿入する必要があります。リストを記述する場合は特に留意してください。

加えてこれを見れば明らかなように、強制改行は行末＋半角スペース 2 つあるいは <br> です。行末＋\ は使えません。

追加された記法

PHP Markdown Extra で追加された記法について、特に属性の追加と略称に関して確認したい。

属性の追加

以下の 4 つの記法に対して属性を追加できます。

  • 見出し
  • Fenced code block
  • リンク
  • 画像

追加できる属性は class と id の 2 つです。

.foo のような . から始まる場合、class=foo と解釈されます。#bar のような # から始まる場合、id=bar と解釈されます。

このいずれかでは無い場合は、そのまま属性として解釈されます。

以下に例を示します。

#### 属性の追加 {#special-attribute}

``` {.html #html-codeblock}
<p>paragraph <b>emphasis</b>
```

[Example Domain](https://www.example.com) {#example-link}

![クラシックオレンジ][F2AC29]

[F2AC29]: https://placehold.jp/F2AC29/ffffff/150x150.png "Classic orange placeholder" {#classic-orange-image}

アンカーリンクの移動が分かりやすいように、脚注にリンクを配置します。[^footnote]

[^footnote]: 属性を追加することで特定のコンテンツにジャンプできる。

    - [見出しへジャンプ](#special-attribute)
    - [コードブロックへジャンプ](#html-codeblock)
    - [リンクへジャンプ](#example-link)
    - [画像へジャンプ](#classic-orange-image)

<p>paragraph <b>emphasis</b>

Example Domain

クラシックオレンジ

アンカーリンクの移動が分かりやすいように、脚注にリンクを配置します。1

Markdown サービスではよく見られる見出しへのアンカーリンクはありません。その代わり、見出しに属性を追加することでアンカーリンクを手動作成できます。

略称

有名な Markdown サービスで採用されていることは少ないですが、以下のようにして <abbr> タグを利用して略称をマウスホバーで表示させることが出来るようになります。

The HTML specification is a recommendation by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

The HTML specification is a recommendation by the W3C.

Leaf blocks なので、脚注のように他の Container blocks を挿入できません。また、laziness も無いので 1 行で表現することが求められます。

加えて、強調等のインライン要素を含めることも出来ません。すべてプレーンテキストとして解釈されます。

理解としては、リンクのタイトルに近いです。

Moodle Markdown を調整する

Moodle Markdown は PHP Markdown Extra に準拠します。記法に関しては以下の 2 つのページ (MoodleDocs) に詳しいです。

ここでは、このフォーラムで Markdown フォーマットを使って投稿する際に生じる問題と解決方法を確認します。

この投稿時点で Moodle v4.4.3 です。

開始する見出しレベル

投稿するディスカッションのタイトルの見出しレベルが 3 になっています。そのため、ディスカッションに見出しを挿入する場合は見出しレベルが 4 以下であると良いでしょう。

実際、見出しレベル 1 を挿入するとタイトルより大きく表示されてしまい奇妙な結果を得ます。（この投稿はレベル 2 から開始しているがやはり大きい）

コードブロックを明示的にする

コードブロックには背景色がありません。そのため、どこからどこまでがコードブロックなのかを判断するのは少々分かりづらいです。

これを解消するために、コードブロックの前後に水平線を与えるかコードの先頭行と末行にコメントアウトで明示すると良いでしょう。

-----
```latex
\documentclass{jlreq}
```
-----

\documentclass{jlreq}

これでも良いですが、この投稿も含めてコードブロックには背景色があります。これを実現するには次のようにします。（markup の部分は何でも良い）

<pre class="language-markup"><code>%% ここから始めて
%% ここにコードを書く
</code></pre>

%% ここから始めて
%% ここにコードを書く

1 行目の <pre> のある行からコードを書き始めると、コードブロックの 1 行目が空白行になるため注意が必要です。

ちなみに、Markdown を使用せずに TinyMCE を使った GUI な入力方法を利用すると、自動的にサンプルコードに背景色が追加されます。

あるいは、コードブロックを <div> で囲んで背景色を追加しても良いです。以下の例での色は TinyMCE で追加されるサンプルコードの背景色と同じです。

<div style="background-color: #F5F2F0" markdown="1">
```tex
\documentclass{article}
```
</div>

\documentclass{article}

もちろん、背景色の他に文字色も変えられるので、次のようにすることも可能です。

<div style="background-color: #FFCCCC; padding-left: 16px;" markdown="1">

border: red 等を追加すれば、コードブロックを囲うことも可能です。

原因

このコードブロックの背景色が無い問題は、Moodle Markdown のパーサを担う php-markdown が ```tex を <pre><code class=language-tex> と変換するのに対して、CSS では pre[class*="language-"] {...} となっているためです。

これに関しては誰が悪いのかよく分かりませんでした。Moodle のバージョンが変わると改善されるかもしれませんが、検証していません。

画像の大きさ

本フォーラムに画像を添付すると、バカデカ画像もそのままのバカデカサイズで表示されてしまいます。

そうとは言っても、Moodle Markdown では画像に属性の追加を使って ![text](image){width=50%} のように幅を調整できません。（<img> でも不可、width 属性を受け入れない？）

そこで、本フォーラムで利用できる属性を探してみたところ、以下の .img-responsive が使えました。これによって、画像の最大横幅がレスポンシブになります。

.img-responsive {
    max-width: 100%;
    height: auto;
}

実際に、横に大きい 1500x150pt の画像に属性を与えてみると次のようになります。

![クラシックブルー][0F4C81]

[0F4C81]: https://placehold.jp/0F4C81/ffffff/1500x150.png "Classic blue placeholder" {#classic-blue-image .img-responsive}

クラシックブルー

数式

TeX forum では数式が利用できます。これは MathJax v2.7.9 です。

$$
  f(x) = \alpha x^2 + \beta x + \gamma
$$

行内数式は利用できません。

表の罫線

表を作成した場合、以下のようになります。

| alpha | beta  |
| ----- | ----- |
| gamma | delta |
alpha beta
gamma delta

罫線がありません。罫線を追加するには、<table border="1"> とする必要がありますが、Markdown ではこれを追加することは出来ません。そのため、表に罫線を課したい場合はすべて HTML で書く必要があります。

折りたたみ

<details> タグを使えば折りたたみを作成できますが、Moodle Markdown ではサニタイズされるため、折りたたみを作成できません。

投稿形式を変更する

本フォーラムの投稿形式のデフォルトは TinyMCE による GUI による入力方法です。

これを Markdown 形式に変更するには、左上のユーザーアイコンから以下のようにします。

  1. ［プレファレンス］
  2. ［エディタプレファレンス］
  3. ［テキストエディタ］
  4. ［プレインテキストエリア］を選択

加えて、投稿する際に［高度］を選択し、フォーマットを［Markdown フォーマット］に変更します。

  1. 属性を追加することで特定のコンテンツにジャンプできる。

    ↩︎