Markdownでドキュメントを書こう
このドキュメントはMarkdownで記述されています。ここではドキュメント編集に必要な表現を、Markdownでどのように書き記すかを解説していきます。
基本のページ編集
新規にページを作成する場合は以下のテキスト部分を必要に合わせて変更して記述してください。
---
sidebar_position:1 <!--サイドバーのどこに表示するかの設定-->
description: <!-- 内容の解説をここに記述 -->
---
# <!-- ここにタイトルを挿入 -->
```md
:::info
この記述の意味
この記述は実際のページには表示されず、サイドバーのどの部分にこのページを配置するかなどの情報を宣言する部分です。
:::
## タイトルと本文
### ページタイトルの設定
ページのタイトルは`#`の後に続くテキストが選ばれます。そのため`#`タグを複数個作ることは望ましくないです。
```md
# <!--ここにタイトルを挿入-->
本文中のセクションの作り方
#はペー ジタイトルとして使われているため、基本的には##から####を用いて使われます。次の例を見てください。
## #を2つ
### #を3つ
#### #を4つ
これは次のような階層になります。
#を2つ
└#を3つ
└#を4つ
他のページを見ればわかるかと思いますが、#の数でタイトル、サブタイトルなどの役割を分けています。
本文の書き方
本文はタグをつけずにそのまま書けばそのまま表示されます。
強調表示
このような強調表示をするには次のように**で囲ってください。
**このような強調表示**
文字の色
文字の色を変えるには次のように書きます
<font color="つけたい色">色を付けたい文字</font>
英語で色を打つだけでなくRGBや16進数も使えます。
ただし#を使って見出しにする際この記述をするとエラーが出ます。
引用
このような斜体表示を するには、次のように*で囲ってください`。
*このような斜体表示*
取り消し線
このような取り消し線表示をするには、次のように~~で囲ってください。
~~このような取り消し線表示~~
箇条書き
- りんご
- バナナ
- みかん
このように書きたい場合は次のように書きます。
- りんご
- バナナ
- みかん
コードを表示する
print("このような表示をするには")
次のように```で囲ってください。
```このようなコード表示```
コメントアウト
Markdownのコード内に実際に表示されないようにメモをしたい場合次のように書きます。
<!--ここに書きたいことを書く-->
このように書くと緑色に表示され実際のページには表示されなくなります。
画像を表示
画像を表示するにはまずそのMarkdownファイルがある場所にimgフォルダを作成しそこに画像を入れます。別にほかのところでもいいですがわかりやすくするためにこのドキュメントはカテゴリごとにimgフォルダがあります。
imgフォルダのhoge.pngという名前の画像を表示したい場合
[]の中は代替テキストで画像が表示されない場合表示されます。
リンクを表示
そのままリンクを打つことで触るとリンク先に行くことができますが次のように打つことでURLを直接表示するのではなくテキストを触ることでリンク先に行くことができるようにします。
[表示したいテキスト](URL)
[STEMASK Docs](https://ask-stem-official.github.io/stemask-docs/)
内部リンク(サイト内の場所)の場合は次のようにファイルパスで指定できます。
[公式チュートリアル](/docs/tutorial-basics/congratulations.md)
ノート
次のように書くことで目立つよう補足説明ができます。
:::note
表示したい内容
:::
ほかにもwarningやcaution、tip、infoなどがあります。
表の作成方法
一応手入力でも書けますが面倒なので次のサイトを使うことをお勧めします。
https://notepm.jp/markdown-table-tool
| No | 都道府県 | 人 口 | 市町村数 |
| :-: | - | -: | -: |
| 1 | 東京都 | 13,942,856 | 39 |
| 2 | 神奈川県 | 9,200,166 | 33 |
| 3 | 大阪府 | 8,823,453 | 43 |
| 4 | 愛知県 | 7,552,873 | 54 |
| 5 | 埼玉県 | 7,337,330 | 63 |
| No | 都道府県 | 人 口 | 市町村数 |
|---|---|---|---|
| 1 | 東京都 | 13,942,856 | 39 |
| 2 | 神奈川県 | 9,200,166 | 33 |
| 3 | 大阪府 | 8,823,453 | 43 |
| 4 | 愛知県 | 7,552,873 | 54 |
| 5 | 埼玉県 | 7,337,330 | 63 |
このように書くことができます。