JavaScriptを有効にしてください

Markdown拡張言語MySTの記法

 ·   5 min read

はじめに

Markdownの拡張言語であるMyST (Markedly Structured Text) について、Markdownから追加された記法を簡単にまとめました。

MySTはPython製のドキュメント生成ツールSphinxで利用できます。利用までのセットアップは以下の記事を参考にして下さい。
SphinxでMarkdown拡張言語のMySTを扱う – Helve Tech Blog

この記事では、MySTでHTMLメタ情報、コメントアウト、HTMLアンカーリンクと相互参照、ReST記法の挿入を行う方法をまとめています。

環境

検証した環境は以下の通りです。また、OSはWindows 10 Home Ver. 21H1を使用しています。

ソフトウェア バージョン
Python 3.8.5
Sphinx 4.4.0
myst-parser 0.17.0

HTMLメタ情報

HTMLメタ情報(metaタグ)について、全てのHTMLに設定する方法と、個別のHTMLに設定する方法があります。全てのHTMLに設定する場合、設定ファイルconf.pyに以下のように記述します。

1
2
3
4
5
language = 'ja'
myst_html_meta = {
    "author": "ここに著者名を書きます。",
    "property=og:locale": "ja_JP"
}

また、個別のHTMLに設定する場合、MySTファイル (.md) の先頭に以下のように記述します。

1
2
3
4
5
---
html_meta:
  "description": "ここに文書の概要を書きます。"
  "keywords": "ここに文書のキーワードを書きます。"
---

先頭にhtml_meta:が必要で、YAML形式となっています。この記述のことをFront-matterと呼びます。

以上の設定でMySTファイルをビルドすると、HTMLには以下のように出力されます。

1
2
3
4
<meta content="ここに著者名を書きます。" name="author" />
<meta content="ja_JP" property="og:locale" />
<meta content="ここに文書の概要を書きます。" name="description" />
<meta content="ここに文書のキーワードを書きます。" name="keywords" />

なお、conf.pyとFront-matterで、同じメタ情報に異なる値を指定した場合、Front-matterの値が優先されます(conf.pyの設定は上書きされる)。

コメントアウト

MySTファイルにコメントを記述する場合、行の先頭に%を置いて、その後にコメントを続けます。コメントはHTMLファイルに出力されません(HTMLのコメント<!-- -->としても出力されません)。

1
2
3
この行はHTMLに出力されます。
% ここにコメントを記述します。
この行はHTMLに出力されます。

HTMLアンカーリンクと相互参照

アンカーリンク

MySTではMarkdownと同様に、見出しのh2, h3タグを#####と記述します。このh2, h3タグには、自動的にアンカーリンクが生成されます(アンカーリンクを利用することで、https//example.com/hoge.html#sectionのように、見出しにリンクを張ることが可能になる)。

1
2
3
## Section

## New Section

上記のMySTファイルをビルドすると、以下のHTMLファイルが出力されます。

1
2
3
4
5
6
7
<div class="section" id="section">
  <h2>Section<a class="headerlink" href="#section" title="このヘッドラインへのパーマリンク"></a></h2>
</div>

<div class="section" id="new-section">
  <h2>New Section<a class="headerlink" href="#new-section" title="このヘッドラインへのパーマリンク"></a></h2>
</div>

このように、見出しが英単語の場合、アンカーリンク (href) は基本的に同じ英単語になります。しかし、以下のように見出しが日本語を含む場合、デフォルトではアンカーリンクはid1, id2, … と割り振られてしまい、見栄えが悪いです。

1
## 章

ビルド結果:

1
2
3
<div class="section" id="id1">
  <h2><a class="headerlink" href="#id1" title="このヘッドラインへのパーマリンク"></a></h2>
</div>

そこで、見出しの前に(...)=と記述することにより、アンカーリンクを指定できます。この記法をTargetと呼びます。

1
2
(my-section)=
## 章

ビルド結果:

1
2
3
<div class="section" id="my-section">
  <span id="id2"></span><h2><a class="headerlink" href="#my-section" title="このヘッドラインへのパーマリンク"></a></h2>
</div>

相互参照

Target記法 (...)= でアンカーリンクを指定した見出しに対して、相互参照(クロスリファレンス)によって簡単にリンクを張ることができます。
相互参照は、{ref}の後にリンク名を記述します。例として、先程の(my-section)=に対する例を示します。

1
{ref}`my-section`を参照してください。

ビルド結果:

1
<a class="reference internal" href="#my-section"><span class="std std-ref"></span></a>を参照してください。

myst-crossref

ReST記法の挿入

ReST記法を挿入する場合、{eval-rst}と記述したコードブロックの内側に書きます。例えば、セル結合されたテーブルを出力したい場合、Markdownは対応していため、ReST記法を使う必要があります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
```{eval-rst}
+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
|              |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+
```

ビルド結果:

rest-table

参考

シェアする

Helve
WRITTEN BY
Helve
関西在住、電機メーカ勤務のエンジニア。X(旧Twitter)で新着記事を配信中です

サイト内検索