記事の編集方法(マークダウン記法)

Published: Nov. 11, 2024, 10:03 a.m. (UTC) / Updated: Nov. 27, 2024, 12:50 a.m. (UTC) 🔖 1 Bookmarks
👍 1 👎 0
日本語

マークダウン記法ガイド

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番目の項目
  1. 最初の項目
  2. 2番目の項目
    1. サブ項目1
    2. サブ項目2
  3. 3番目の項目

チェックリスト

- [x] 完了したタスク
- [ ] 未完了のタスク
  - [x] サブタスク1
  - [ ] サブタスク2
  • 完了したタスク
  • 未完了のタスク
    • サブタスク1
    • サブタスク2

リンクと画像

リンク

[表示テキスト](https://pinotwalk.com/)


[1]: https://pinotwalk.com
[reference]: https://pinotwalk.com "PinotWalk"

表示テキスト
参照リンク
名前付き参照リンク

画像貼り付け

PiotWalkでは貼り付けたい画像は、編集画面下方のファイル選択ボタンから選択してから、upload imageボタンを押すことで実装しています。編集ボックスのカーソルがある位置に画像が挿入されます。この際のファイル名は、一つのアカウントに対してユニークに設定されます。(別のブログで同じファイル名を使うと衝突して最初にアップロードしたファイル名の画像が表示されます。)

![filename](https://XXXXXXXXX/filename.jpeg)

引用

基本的な引用

> これは引用文です。
> 複数行に渡って引用することもできます。
> 改行することが出来ます。
> 
> 
> 
> 複数の改行はサニタイズされます。

これは引用文です。
複数行に渡って引用することもできます。
改行することが出来ます。

複数の改行はサニタイズされます。

ネストされた引用

> 外側の引用
>> 内側の引用
>>> さらに内側の引用

外側の引用

内側の引用

さらに内側の引用

引用内での他の要素の使用

> ### 引用内の見出し
> 
> - リスト項目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

ベストプラクティス

  1. 一貫性を保つ

    • 同じ種類の見出しには同じレベルを使用
    • リストの記号は統一する
    • インデントは揃える
  2. 読みやすさを重視

    • 適切な空行を入れる
    • 長い文書は見出しで整理する
    • 表は必要な時のみ使用
  3. メンテナンス性

    • 複雑な構造は避ける
    • コメントを適切に使用
    • 画像やリンクは管理しやすい形式で
  4. アクセシビリティ

    • 画像には適切な代替テキストを設定
    • 色だけでなく形状でも情報を伝える
    • スクリーンリーダーを考慮した構造化

トラブルシューティング

よくある問題と解決方法

  1. リストが正しく表示されない

    • リストの前後に空行があるか確認
    • インデントが正しいか確認
    • 混合リストの場合、階層を確認
  2. 改行が効かない

    • 行末に半角スペースを2つ入れてみる
    • 必要に応じて<br>タグを使用
    • <br>タグの前に改行を入れる
  3. URL/画像が表示されない

    • URLが正しいか確認
    • 画像ファイル名が存在するか確認
    • もう一度アップロードしてみる
  4. テーブルが崩れる

    • 列数が各行で一致しているか確認
    • 区切り線の-が各列で3つ以上あるか確認
    • |の位置が揃っているか確認

まとめ

マークダウンは非常に柔軟で強力な記法です。基本的な記法を覚えれば、すぐに実用的な文書を作成できます。必要に応じて高度な機能を使用することで、より表現力豊かな文書を作成することができます。

このガイドを参考に、実際に文書を作成しながら練習することをお勧めします。使えば使うほど、マークダウンの便利さを実感できるはずです。


注意: プラットフォームによってサポートされる記法が異なる場合があります。


  1. これは脚注1の内容です。 ↩︎

  2. これは脚注2の内容です。 ↩︎

Comments