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の参考

• sphinx 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)
画像リンク	
リンク定義	[link]: https://github.com
参照リンク	[title][link]
順序付きリスト	1. item 2. item
順序なしリスト	- item - item
コード	```lang hogehoge ```
コメント	% comment

Markdownの参考

• MySt

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;
```

graph TD; A-->B; A-->C; B-->D; C-->D;

SphinxでのMermaidの実用

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

Mermaidの参考

• mermaid

画像の貼り付けについて

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

固定方法

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

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

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

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