Markdownリファレンス

この記事では、WSOFTDocsを執筆する際に使用できるマークダウン記法について説明します。

taiseiue | 2022-12-01

WSOFTDocsの記事は、すべてMarkdown記法で記述します。 WSOFTDocsでは、記事のMarkdownは、Pymdownを用いてビルドしています。また、WSOFTDocsでは、このサイト内で独自に表現できるMarkdown記法も導入しています。

どのエディターを使用してもMarkdownを記述できますが、Markdown All in One 拡張機能を導入したVS Codeで記述することをおすすすめします。

テキスト

テキストの装飾について詳しく知るには、テキストの書式設定に関する指針を参照してください。

普通のテキストは、そのまま記述します。

Markdown

Lantanaは、シンプルで軽量なMKDocsのテーマです。
HTMLの知識がなくても簡単にサイトを作成できます。

段落を分けるには、一行空行を挟みます。

結果

Lantanaは、シンプルで軽量なMKDocsのテーマです。 HTMLの知識がなくても簡単にサイトを作成できます。

段落を分けるには、一行空行を挟みます。

改行

文中で段落を分けずに改行する場合や、二行以上にわたって改行したい場合には、改行したい位置にHTMLの<br/>タグを使用します。

Markdown

この文は段落を分けずに改行しています。<br/>
ここは上の文から改行されています。

結果

この文は段落を分けずに改行しています。
ここは上の文から改行されています。

エスケープ

Markdown記法で意味のある文字（たとえば、*や#など）をテキストとして表示するには、エスケープが必要です。

Markdown

\#これはヘッダーにはなりません

\*これは斜体にはなりません\*

結果

#これはヘッダーにはなりません

*これは斜体にはなりません*

記事にコメントを記述する方法はHTMLと同じです。コメントはビルド時に削除されます。

Markdown

<!-- this is a comment. -->

機密事項をコメントに残さない

記事中のコメントはビルド時に削除されますが、ソース上では残ります。記事中のコメントはGitHubで閲覧できることにご注意ください。

太字・斜体

テキスト中で斜体にしたい場所を*または_で、太字にしたい場所を**または__で囲むことで、それぞれ斜体と太字を表現できます。斜体と太字は同時に使用できます。ただし、_を使用するには左右に空白が必要です。

Markdown

これは*斜体*になります。これも _同様_ です。

これは**太字**になります。これも __同様__ です。

これは***斜体および太字***になります。これも ___同様___ です。

結果

これは斜体になります。これも同様です。

これは太字になります。これも同様です。

これは斜体および太字になります。これも同様です。

下線・打ち消し線

テキスト中で下線を引きたい場所を^^で、打ち消し線を引きたい場所を^^を囲むことで、下線と打ち消し線を表現できます。

Markdown

ここには^^下線^^が引かれます。

ここには~~打ち消し線~~が引かれます。

結果

ここには^{^下線}^が引かれます。

ここには_{~打ち消し線}~が引かれます。

上付き文字・下付き文字

テキスト中で上付き文字にしたい場所を^で、下付き文字にしたい場所を^~で囲むことで、上下付き文字を表現できます。

Markdown

これは^上付き文字^になります。

これは~下付き文字~になります。

結果

これは^{上付き文字}になります。

これは_{下付き文字}になります。

ハイライト

テキスト中でハイライトをつけたい場所に==をつけることで、背景色を強調色にできます。

Markdown

この場所に ==ハイライト== がつきます。

結果

この場所にハイライトがつきます。

ハイライトの制約

ハイライトをつける際、==の周りには空白や読点など、単語として分割できる要素が必要です。

キーボードショートカット

キーの組み合わせを表現するには、小文字のキー名を++で囲みます。キー同士は+で繋げます。

Markdown

Windowsでセキュリティオプションを表示するには++ctrl+alt+del++を押します。

結果

Windowsでセキュリティオプションを表示するにはCtrl+Alt+Delを押します。

インラインコード

テキスト中にコードを含めるには、`で囲みます。

Markdown

AliceScriptでテキストを表示するには、`print`関数を使います。

結果

AliceScriptでテキストを表示するには、print関数を使います。

見出し

Hタグを生成します。記事にタイトルが指定されていない場合、自動的に記事の一番最初の見出しがタイトルになります。記事中の見出しには、H2～H4見出しを使用してください。

見出しは目次にも表示されます。

Markdown

## これはH2タグになります
#### これはH4タグになります

結果

これはH2タグになります

これはH4タグになります

脚注

対応バージョン:>=2.7.1

[^1]のように文章の任意の場所に脚注へのリンクを設置すると、ページの末尾の説明へ移動します。説明は文章中の任意の場所で[^1]: <説明>とすることで記述できます。

考慮事項

脚注機能は確かに便利ですが、ユーザーがそれを参照するたびにページ末尾に移動しなければならないことに注意してください。ひとつの記事に大量に脚注があったり、そこに重要なことが書いてある場合ユーザー体験を極端に低下させます。重要なことは直接文中に記述するように心がけてください。

例

そのころわたくしは、モリーオ市の博物局に勤めて居りました。
十八等官 [^1]でしたから役所のなかでも、ずうっと下の方でしたし俸給[^2]もほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。

[^1]: ロシア帝国では、軍隊、政府、および宮廷における地位と階級を**[官等表](https://en.wikipedia.org/wiki/Table_of_Ranks)**と呼ばれるもので管理していました。
[^2]: 役所や会社に務める人の給料のことを指す言葉です。

結果

そのころわたくしは、モリーオ市の博物局に勤めて居りました。十八等官¹ でしたから役所のなかでも、ずうっと下の方でしたし俸給²もほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。

コードブロック

``` で囲むことでコードとして認識され、言語インジケーター(```言語名)をつけることで、シンタックスハイライトがつきます。また、title="タイトル"とすることでファイル名などのタイトルを表示できます。

Markdown

``` csharp title="Program.cs"
using System;

public class Program
 {
    public static void Main()
     {
            Console.WriteLine("Hello World!");
     }
 }
 ```

結果

Program.cs

using System;

public class Program
 {
    public static void Main()
     {
            Console.WriteLine("Hello World!");
     }
 }

WSOFTDocsでのコードブロックのお作法については、コードの埋め込み方を参照してください。

数式

\$\$で囲むことでTeX記法を用いて数式を記述できます。

Markdown

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

結果

\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

$または$...$で囲むことで、数式を文中に埋め込むこともできます。

Markdown

ディッフィー・ヘルマン鍵共有プロトコルでは、まず大きな素数 ${\displaystyle p}p$ と、
${\displaystyle p-1}p-1$ を割り切る大きな素数 ${\displaystyle q}q$ を用意します。
また、 ${\displaystyle g}g$ を
${\displaystyle ({\mathbb {Z} }/p{\mathbb {Z} })^{\ast }}{\displaystyle ({\mathbb {Z} }/p{\mathbb {Z} })^{\ast }}$ の元で、
位数が ${\displaystyle q}q$ である値とします。
この ${\displaystyle p,q,g}{\displaystyle p,q,g}$ の値は公開されているものとします。

結果

ディッフィー・ヘルマン鍵共有プロトコルでは、まず大きな素数 ${\displaystyle p}p$ と、 ${\displaystyle p-1}p-1$ を割り切る大きな素数 ${\displaystyle q}q$ を用意します。また、 ${\displaystyle g}g$ を ${\displaystyle ({\mathbb {Z} }/p{\mathbb {Z} })^{\ast }}{\displaystyle ({\mathbb {Z} }/p{\mathbb {Z} })^{\ast }}$ の元であり、位数が ${\displaystyle q}q$ である値とします。この ${\displaystyle p,q,g}{\displaystyle p,q,g}$ の値は公開されているものとします。

順序なしリスト

リストの上には空行が必要です。

Markdown

* 文頭に"*"、"+"、"-"のいずれかを入れると順序なしリストになります
+ 記号のあとには**スペースが必要**です
- 同じリストでは同じ記号を使うことを推奨します。

結果

文頭に"*"、"+"、"-"のいずれかを入れると順序なしリストになります
記号のあとにはスペースが必要です
同じリストでは同じ記号を使うことを推奨します。

番号付きリスト

リストの上には空行が必要です。

Markdown

1. 文頭に"数字."を入れると番号付きリストになります。
1. "数字."のあとには**スペースが必要**です
1. すべての数字を1にすると、自動的に番号が付きます。

結果

文頭に"数字."を入れると番号付きリストになります。
"数字."のあとにはスペースが必要です
すべての数字を1にすると、自動的に番号が付きます。

タスクリスト

順序なしリストの記述の後ろに[]を入れるとチェックボックスが生成されます。また、チェックが入った状態のボックスを生成する場合は[x]を入力します。

Markdown

- [ ] タスク1
- [x] タスク2

結果

タスク1
タスク2

水平線

Markdown

---

結果

URL

Urlやメールアドレスを書くだけで、自動的にリンクになります。

Markdown

https://lantana.wsoft.ws

[email protected]

結果

https://lantana.wsoft.ws

info@wsoft.ws

リンク

Markdown

[リンク](about:blank)

結果

リンク

WSOFTDocsでのリンクのお作法については、リンクの使い方を参照してください。

タイトル付きリンク

タイトルはリンクをホバーした時に表示されます。

Markdown

[リンク](about:blank "タイトル")

結果

リンク

リンクの使いまわし

Markdown

[link]: about:blank
[ここ][link]と[ここ][link]は同じになります。

結果

こことここは同じになります。

また、linkという書き方もできます。

セレクター

ユーザーの状況に応じて複数のどちらかのサイトにリンクしたい場合、セレクターを使用できます。セレクターを使用するには、引用の先頭に[!SELECTOR] タイトルをつけ、引用中にリンクを列挙します。

Markdown

> [!SELECTOR] 対象バージョンを選択
> [Alice2.3以前](../products/alice/api/alice/function.md)
> [Alice3.0以降](../products/alice/general/function.md)

ボタン

ボタンを使えば、ユーザーにとって注意を引きやすいリンクを作ることができます。ボタンはBootstrapによって提供されているため、クラスを指定するだけで使用できます。次に例を示します。

Markdown

[ボタン](#){: .btn .btn-primary }
[ボタン](#){: .btn .btn-secondary }
[ボタン](#){: .btn .btn-success }
[ボタン](#){: .btn .btn-danger }
[ボタン](#){: .btn .btn-warning }
[ボタン](#){: .btn .btn-info }
[ボタン](#){: .btn .btn-light }
[ボタン](#){: .btn .btn-dark }
[ボタン](#){: .btn .btn-link }

結果

ボタンボタンボタンボタンボタンボタンボタンボタンボタン

画像

Markdown

![Aliceが微笑んでいる](./media/alice.jpg)

結果

Aliceが微笑んでいる

表

次のように記述することで簡単に表を使用できます。ちなみに、名前のあとの空白はMarkdownの読みやすさのためで出力結果には影響しません。

Markdown

名前     | 年齢
-------  | ----
山田 太郎 | 16
鈴木 花子 | 24

結果

名前	年齢
山田太郎	16
鈴木花子	24

両端に|を使用することで、読みやすくできます。

Markdown

|名前     | 年齢|
|-------  | ----|
|山田 太郎 | 16  |
|鈴木 花子 | 24  |

結果

名前	年齢
山田太郎	16
鈴木花子	24

ヘッダーの区切りにコロンを追加すると、左右中央揃えを使用できます。ヘッダーでは左右中央揃えが適用されません。

Markdown

| Left align | Right align | Center align |
|:-----------|------------:|:------------:|
| This       | This        | This         |
| column     | column      | column       |
| will       | will        | will         |
| be         | be          | be           |
| left       | right       | center       |
| aligned    | aligned     | aligned      |

結果

Left align	Right align	Center align
This	This	This
column	column	column
will	will	will
be	be	be
left	right	center
aligned	aligned	aligned

引用

Markdown

> 文頭に>を置くことで引用になります。
> 複数行にまたがる場合、改行のたびにこの記号を置く必要があります。
> 
> 引用の中に別のMarkdownを使用することも可能です。
> 
> > これはネストされた引用です。

結果

文頭に>を置くことで引用になります。複数行にまたがる場合、改行のたびにこの記号を置く必要があります。

引用の中に別のMarkdownを使用することも可能です。

これはネストされた引用です。

図形

Lantanaは規定でmermaid.jsをサポートします。mermaid.jsを使うと、複雑な図形を簡単に挿入できます。

Markdown

```mermaid
graph LR;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

結果

アラート

アラートを使用すると、記事の重要な部分を色とアイコンを使用して目立たせることができます。

アラートは、記事の中で3つまでにしてください。

適用したい引用符の任意の行に[!種類]を追加します。

Markdown

> [!NOTE] メモ
> 流し読みしているユーザーにも読んでもらいたい情報を記述します。

結果

メモ

流し読みしているユーザーにも読んでもらいたい情報を記述します。

アラートのバリエーション

用途に応じて、アラートには様々な色やアイコンを使用できます。次に例を示します。

NOTE

Note

NOTEで使用できる装飾です。リンクは自動的に適切な色になります。