Markdownしたい（myst_parser）

$ pip3 install myst-parser

 1extensions = [
 2              "myst_parser",
 3              ]
 4
 5# -- Options for MyST Parser -------------------------------------------------
 6
 7myst_enable_extensions = [
 8    "amsmath,
 9    "attrs_block",
10    "attrs_inline",
11    "colon_fence",
12    "deflist",
13    "dollarmath",
14    "fieldlist",
15    "html_admonition",
16    "html_image",
17    # "linkify",
18    "replacements",
19    "smartquotes",
20    "strikethrough",
21    "substitution",
22    "tasklist",
23]

MyST Parserは、Sphinx文書をMarkdown形式で書けるようにする拡張パッケージです。 すでにMarkdown記法に慣れている場合は、迷わずこの拡張を追加しましょう。

conf.pyのextentionsにmyst_parserを追加します。 conf.py の適当な場所にmyst_enable_extensions = [...]を定義して、MyST Parserのオプションを有効にします。 オプションはSyntax Extensionsを参照してください。 コピペしてすべて有効にして使えばOKだと思いますが、自分の必要にあったオプションを選択してください。

警告

linkfyは別のパッケージが必要なため、コメントアウトしています。

ディレクティブしたい

ディレクティブ（directives）は段落などのブロック要素をマークアップするときに使います。

MyST記法の場合、コードブロック記法のように書きます。 また、ディレクティブには引数とオプションをとるものもあります。 オプションは---で区切った範囲にYAML形式でキー: 値を指定します。

1```{ディレクティブ名} 引数
2---
3オプション1: 値1
4オプション2: 値2
5---
6内容内容内容内容内容内容内容内容
7内容内容内容内容内容内容内容内容
8内容内容内容内容内容内容
9```

1.. ディレクティブ:: 引数
2   :オプション1: 値1
3   :オプション2: 値2
4
5   内容内容内容内容内容内容内容内容
6   内容内容内容内容内容内容内容内容
7   内容内容内容内容内容内容

コロンフェンスしたい（colon_fence）

1:::{ディレクティブ名} 引数
2---
3オプション1: 値1
4オプション2: 値2
5---
6内容内容内容内容内容内容内容内容
7内容内容内容内容内容内容内容内容
8内容内容内容内容内容内容
9:::

colon_fenceオプションを有効にすると```{ディレクティブ名}の代わりに:::{ディレクティブ名}で書けるようになります。

ロールしたい

1{ロール}`ラベル名`

1:ロール:`ラベル名`

ロール（roles）は文章中の単語などのインライン要素をマークアップするときに使います。

ヒント

Sphinxドキュメントをマークアップするときに、このロールとディレクティブの役割と使い分けを理解するのはとても大切だと思います。

属性したい（attrs_block）

{#id名 .クラス名}
## 記事の見出し

記事の本文。記事の本文。記事の本文。記事の本文。記事の本文。
記事の本文。記事の本文。記事の本文。記事の本文。記事の本文。
記事の本文。記事の本文。記事の本文。記事の本文。記事の本文。

attrs_blockを有効にすると、ブロック要素に属性（#idや.classなど）を追加できます。 Markdown記法はシンプルでよいのですが、SSG（＝静的サイトジェネレーター）するときはちょっと不便に感じていました。 これは、それを解決するための拡張です。

属性したい（attrs_inline）

attrs_inlineを有効にすると、インライン要素に対して属性（#idや.classなど）を追加できます。

1{ロール}`ラベル名`{.クラス名}

<span class="クラス名">ラベル名</span>

置換したい（sub-ref）

1{sub-ref}`today`
2{sub-ref}`wordcount-words`
3{sub-ref}`wordcount-minutes`

参考

  • 更新日: 2024-04-26

  • このページの単語数: 39 単語

  • 読む時間の目安: 0 分

sub-refロールを使うと、キーワードを置換できます。

メタデータしたい

1language = "ja"
2myst_html_meta = {
3    "description lang=ja": "サイトの説明",
4    "keywords": "Sphinx, KumaROOT",
5    "property=og:locale":  "ja_JP"
6}

メタデータは、サイト全体と記事ごとのそれぞれに設定できます。 サイト全体のメタデータはconf.pyのmyst_html_metaで設定します。

---
myst:
  html_meta:
    "description lang=ja": "記事の説明"
    "keywords": "Sphinx, 記事のキーワード"
    "property=og:locale": "ja_JP"
---

記事ごとのメタデータはフロントマターで設定します。

リファレンス