Learned Stackの書き方

このサイトで使える記述法の説明、用途及びおおまかな設定について

  • reStructuredText

  • Markdown

  • mermaid

reStructuredText

Sphinxで標準となっているマークアップ言語で、特に設定をせずに使用することができる
reStructuredTextでは目次機能を容易に利用できるため、主に目次の生成に利用する

reStructuredTextの記述方法

要素

構文

H1

===

H2

---

H3

^^^

```
.. toctree::
   :maxdepth: 1
   :caption: Content
   hoge
   huga
   example

```

toctreeの生成は
.rstもしくは.mdファイルに対するpathを記述する

reStructuredTextの参考

Markdown

Githubなどで特に書き慣れた(筆者の個人的な話)マークアップ言語で、拡張機能を利用することにより使用できる
Markdownは主に、コンテンツ本文の記述に利用する

Markdownインストール方法

MySTという拡張機能を利用することでMarkdownでの記述が可能になる
$ pip install myst-parser

SphinxでMySTを有効にする方法

conf.pyファイルに以下の記述をする

extensions = ["myst_parser"]

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

これによりMySTパーサーの拡張機能が有効になり、.mdの拡張子をもつドキュメントが全て解析される

Markdownでの記述方法

要素

構文

H1

#

H2

##

H3

###

H4

####

H5

#####

H6

######

太字

**bold**

イタリック

*italic*

インラインコード

`code`

引用

> quote

テーマ別ブレイク

---

自動リンク

<https://github.com>

URLリンク

[github](https://github.com)

画像リンク

![alt](https://github.com)

リンク定義

[link]: https://github.com

参照リンク

[title][link]

順序付きリスト

1. item
2. item

順序なしリスト

- item
- item

コード

```lang
hogehoge
```

コメント

% comment

Markdownの参考

Mermaid

notionやgithubで使い慣れているとともに
学習内容の記録の際にDiagramの挿入ができると表現の幅が広がる

Mermaidインストール方法

sphinxcontrib.mermaidによってMySTを利用してMermaidを使用できるように拡張できる

pip install sphinxcontrib-mermaid

有効にする方法

conf.py

extensions = [
    "myst-parser",
    "sphinxcontrib.mermaid",
]

Mermaidの記述例

```{mermaid}
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

A

B

C

D

SphinxでのMermaidの実用

正直うまく出力できないことが多い
うまくいかない時はNotionもしくはGithubで図を作成し、スクショを撮って画像として貼り付ける方法をとる

Mermaidの参考

画像の貼り付けについて

画像はサイズが大きすぎるとページ全体のスタイルが崩れてしまう(特にスマートフォン)ので、サイズを固定する方法をとる
サイズは横幅360pxに固定する

固定方法

  • 横幅360pxの画像を生成する

  • ffmpeg等で360pxに等倍加工をする

  • pipでインストールしたthemeのデフォルトのCSS設定でimgタグのwidthを360pxにする

$ ffmpeg -i INPUT_FILE -vf "scale=360:-1" -q 2 OUTPUT_FILE