マークダウン記法ガイド
PinotWalkではマークダウン記法で記事を編集します。PinotWalkでは、表現の一貫性を保つためにhtmlの全ての記法はカバーしない方針です。しかし、基本的なマークダウンの記法はカバーする方針としています。
はじめに
マークダウンは、2004年にJohn Gruberによって作られた軽量マークアップ言語です。プレーンテキストを使って文書を作成し、HTMLに変換することができます。
マークダウンの利点
- 読みやすく書きやすい
- シンプルな記法
- 多くのプラットフォームでサポート
- テキストエディタがあれば編集可能
見出し
見出しには6段階あります：
# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6
見出し1
見出し2
見出し3
見出し4
見出し5
見出し6
代替構文：
見出し1
=======
見出し2
-------
見出し1
見出し2
重要なポイント：
- 見出しの前後には空行を入れる
#の後にはスペースを入れる- 見出しは階層構造を意識して使用する
段落とテキスト装飾
段落
段落は空行で区切ります。
これは1つ目の段落です。
これは2つ目の段落です。
これは1つ目の段落です。
これは2つ目の段落です。
改行
文章であれば改行か<br>で反映されます。文章と文章の間に開業を入れる場合には<br>を記入します。
テキスト装飾
**太字**
__太字__
*斜体* *italic*
_斜体_ _italic_
***太字と斜体 italic***
___太字と斜体___
~~打ち消し線~~
`インラインコード`
上付き文字: X<sup>2</sup>
下付き文字: H<sub>2</sub>O
実際の表示：
太字
斜体 italic
斜体 italic
太字と斜体 italic
打ち消し線
インラインコード：
- 上付き文字: X2
- 下付き文字: H2O
ハイライト
==ハイライト==
ハイライト
文字色
文字色は通常は以下のようなhtml記法で対応しますが、PinotWalkでは利用出来ない設定となっています。
<span style="color: red;">赤文字</span>
赤文字
リスト
箇条書きリスト
- 項目1
- 項目2
- サブ項目1
- サブ項目2
- サブサブ項目
- 項目3
* 項目a
* 項目b
+ 項目A
+ 項目B
- 項目1
- 項目2
- サブ項目1
- サブ項目2
- サブサブ項目
- 項目3
- 項目a
- 項目b
- 項目A
- 項目B
番号付きリスト
1. 最初の項目
2. 2番目の項目
1. サブ項目1
2. サブ項目2
3. 3番目の項目
- 最初の項目
- 2番目の項目
- サブ項目1
- サブ項目2
- 3番目の項目
チェックリスト
- [x] 完了したタスク
- [ ] 未完了のタスク
- [x] サブタスク1
- [ ] サブタスク2
- 完了したタスク
- 未完了のタスク
- サブタスク1
- サブタスク2
リンクと画像
リンク
[表示テキスト](https://pinotwalk.com/)
[1]: https://pinotwalk.com
[reference]: https://pinotwalk.com "PinotWalk"
画像貼り付け
PiotWalkでは貼り付けたい画像は、編集画面下方のファイル選択ボタンから選択してから、upload imageボタンを押すことで実装しています。編集ボックスのカーソルがある位置に画像が挿入されます。この際のファイル名は、一つのアカウントに対してユニークに設定されます。（別のブログで同じファイル名を使うと衝突して最初にアップロードしたファイル名の画像が表示されます。）
引用
基本的な引用
> これは引用文です。
> 複数行に渡って引用することもできます。
> 改行することが出来ます。
>
>
>
> 複数の改行はサニタイズされます。
これは引用文です。
複数行に渡って引用することもできます。
改行することが出来ます。複数の改行はサニタイズされます。
ネストされた引用
> 外側の引用
>> 内側の引用
>>> さらに内側の引用
外側の引用
内側の引用
さらに内側の引用
引用内での他の要素の使用
> ### 引用内の見出し
>
> - リスト項目1
> - リスト項目2
>
> **太字** や *斜体* も使えます。
引用内の見出し
- リスト項目1
- リスト項目2
太字 や 斜体 も使えます。
コードの記述
インラインコード
文中に`コード`を入れる場合はバッククォートで囲みます。
文中にコードを入れる場合はバッククォートで囲みます。
コードブロック
```言語名
コードブロック
複数行に渡って記述可能
```
対応している言語の例：
-
python
```python def hello(): print("Hello, World!") ``` -
javascript
```javascript function hello() { console.log("Hello, World!"); } ``` -
css
```css body { background-color: #f0f0f0; } ```
シンタックスハイライト
多くのマークダウンプロセッサは以下の言語をサポート：
- HTML, CSS, JavaScript
- Python, Ruby, PHP
- Java, C++, C#
- その他多数
表
基本的な表
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
| 列1 | 列2 | 列3 |
|---|---|---|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
セルの位置合わせ
| 左揃え | 中央揃え | 右揃え |
|:-------|:--------:|-------:|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
| 左揃え | 中央揃え | 右揃え |
|---|---|---|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
複雑な表
| 項目 | 説明 | 備考 |
|------|------|------|
| 項目1 | 複数行に<br>渡る説明 | 備考1 |
| 項目2 | *斜体* や **太字** が使える | 備考2 |
| 項目3 | `コード` や [リンク](URL) も可能 | 備考3 |
| 項目 | 説明 | 備考 |
|---|---|---|
| 項目1 | 複数行に 渡る説明 |
備考1 |
| 項目2 | 斜体 や 太字 が使える | 備考2 |
| 項目3 | コード や リンク も可能 |
備考3 |
その他の要素
水平線
以下のいずれかを使用（3つ以上）：
---
***
___
コメント
<!-- これはコメントです。表示されません -->
⇒ 表示されません
脚注
本文中に脚注[^1]を入れることができます。
本文中に脚注[^2]を入れることができます。
[^1]: これは脚注1の内容です。
[^2]: これは脚注2の内容です。
本文中に脚注[1]を入れることができます。文末に脚注1が表示されます。
本文中に脚注[2]を入れることができます。文末に脚注2が表示されます。
目次の自動生成
PinotWalkではマークダウン記法で記述された構造に従って目次を自動生成します。
拡張マークダウン記法
数式（LaTeX記法）
インライン数式: $E = mc^2$
ブロック数式:
$$
\frac{d}{dx}e^x = e^x
$$
$$
|\psi_+|^2 =N^2 (|\phi_1|^2 +|\phi_2|^2 + 2\Re(\phi_1^*\phi_2))
$$
インライン数式: $E = mc^2$
ブロック数式:
$$
\frac{d}{dx}e^x = e^x
$$
$$
|\psi_+|^2 = N^2 (|\phi_1|^2 +|\phi_2|^2 + 2\Re(\phi_1^* \phi_2))
$$
行列の改行はイレギュラーです。 通常は\\で改行ですが、PinotWalkでは\\\\と書きます。
$$
\begin{pmatrix}
0 & 1 \\\\
1 & 0
\end{pmatrix}
$$
$$
\begin{pmatrix}
0 & 1 \\
1 & 0
\end{pmatrix}
$$
- その他の制限
-
かっこ
\left{、\right}は利用出来ません。通常の{}を使ってください。$ \left{ abc \right} $$ \left{ abc \right} $
-
下付き字と改行
Latexの下付きの記号_と、マークダウンの イタリック体 記号_が衝突するため表示に不具合が起きる場合があります。その場合はスペースや改行を入れることで調整することが出来ます。$$ \phi^{abc}_{efg} $$ #ここに改行が無い $$ \hat{\sigma_x}_{xyz} $$ TThis is $\phi^{abc}_{efg}$, $\hat{\sigma_x}_{xyz}$ that is $\hat{\sigma_x}_{xyz}$.【表示不具合の例】
$$
\phi^{abc}{efg}
$$
$$
\hat{\sigma}{xyz}
$$This is $\phi^{abc}{efg}$, $\hat{\sigma_x}{xyz}$ that is $\hat{\sigma_x}_{xyz}$.
$$ \phi^{abc}_{efg} $$ #ここに改行がある $$ \hat{\sigma_x}_{xyz} $$ This is $\phi^{abc}_{efg}$, $\hat{\sigma_x}_{xyz}$ that is $\hat{\sigma_x}_{xyz}$.【改善例】
$$
\phi^{abc}_{efg}
$$$$
\hat{\sigma_x}_{xyz}
$$This is $\phi_{efg}^{abc}$, that is $\hat{\sigma_x}_{xyz}$.
-
折りたたみセクション
<details>
<summary>クリックして展開</summary>
> ここに詳細な内容を書きます。
> 改行も出来ます。
</details>
クリックして展開
ここに詳細な内容を書きます。
改行も出来ます。
キーボードキー
<kbd>Ctrl</kbd> + <kbd>C</kbd>
Ctrl + C
ベストプラクティス
-
一貫性を保つ
- 同じ種類の見出しには同じレベルを使用
- リストの記号は統一する
- インデントは揃える
-
読みやすさを重視
- 適切な空行を入れる
- 長い文書は見出しで整理する
- 表は必要な時のみ使用
-
メンテナンス性
- 複雑な構造は避ける
- コメントを適切に使用
- 画像やリンクは管理しやすい形式で
-
アクセシビリティ
- 画像には適切な代替テキストを設定
- 色だけでなく形状でも情報を伝える
- スクリーンリーダーを考慮した構造化
トラブルシューティング
よくある問題と解決方法
-
リストが正しく表示されない
- リストの前後に空行があるか確認
- インデントが正しいか確認
- 混合リストの場合、階層を確認
-
改行が効かない
- 行末に半角スペースを2つ入れてみる
- 必要に応じて
<br>タグを使用 <br>タグの前に改行を入れる
-
URL/画像が表示されない
- URLが正しいか確認
- 画像ファイル名が存在するか確認
- もう一度アップロードしてみる
-
テーブルが崩れる
- 列数が各行で一致しているか確認
- 区切り線の
-が各列で3つ以上あるか確認 |の位置が揃っているか確認
まとめ
マークダウンは非常に柔軟で強力な記法です。基本的な記法を覚えれば、すぐに実用的な文書を作成できます。必要に応じて高度な機能を使用することで、より表現力豊かな文書を作成することができます。
このガイドを参考に、実際に文書を作成しながら練習することをお勧めします。使えば使うほど、マークダウンの便利さを実感できるはずです。
注意: プラットフォームによってサポートされる記法が異なる場合があります。
Comments