Markdownリファレンス
この記事では、WSOFTDocsを執筆する際に必要なマークダウン記法を表します。
Markdown記法は、簡単で軽量なマークアップ言語です。WSOFTDocsでは、Jinja解析エンジンを介して解析されます。
普通のテキスト
そのまま記述可能です。
結果Lantanaは、シンプルで軽量なMKDocsのテーマです。 HTMLの知識がなくても簡単にサイトを作成できます。
改行するには、一行空行を挟みます。
エスケープ
マークダウンで意味のある文字(たとえば、*や#など)をテキストとして表示するには、エスケープが必要です。
結果
*#!`\
明示的な空行
二行以上にわたって改行したい場合など、一部の場合ではHTMLの<br/>
タグを使用します。
コメント
記事にコメントを記述する方法はHTMLと同じです。ビルド時に削除されます。
見出し
Hタグを生成します。記事にタイトルが指定されていない場合、自動的に記事の一番最初の見出しがタイトルになります。
また、見出しは目次にも表示されます。
結果これはH1タグになります
これはH2タグになります
これはH6タグになります
テキストの装飾
文章をさまざまに装飾する方法をまとめて紹介します。
_ か * で囲むとHTMLのemタグになり、 *このように* 表示されます。
__ か ** で囲むとHTMLのstrongタグになり、**このように** 表示されます。
それらを組み合わせることもできます。*** で囲むと、***このように*** 表示されます。
~~ で囲むと打消し線になり、 ~~このように~~ 表示されます。
^^ で囲むと下線がつき、^^このように^^ 表示されます。
== で囲むとハイライトがつき、==このように== 表示されます。
~ で囲むと下付き文字になり、使用すると~このように~表示されます。
^ で囲むと上付き文字になり、使用すると^このように^表示されます。
++ で囲むと++ctrl+alt+del++のようにキーボードのキーを表現できます。
また、`print("Hello,World!");`と記述することでコードをインライン表示できます。
__ か ** で囲むとHTMLのstrongタグになり、このように 表示されます。
それらを組み合わせることもできます。*** で囲むと、このように 表示されます。
~~ で囲むと打消し線になり、 このように 表示されます。
^^ で囲むと下線がつき、このように 表示されます。
== で囲むとハイライトがつき、このように 表示されます。
~ で囲むと下付き文字になり、使用するとこのように表示されます。
^ で囲むと上付き文字になり、使用するとこのように表示されます。
++ で囲むとCtrl+Alt+Delのようにキーボードのキーを表現できます。
また、print("Hello,World!");
と記述することでコードをインライン表示できます。
テキストの装飾について詳しく知るには、テキストの書式設定に関する指針を参照してください。
脚注
対応バージョン:<=2.7.1
[^1]
のように文章の任意の場所に脚注へのリンクを設置すると、ページの末尾の説明へ移動します。
説明は文章中の任意の場所で[^1]: <説明>
とすることで記述できます。
使用に注意
脚注機能は確かに便利ですが、ユーザーがそれを参照するたびにページ末尾に移動しなければならないことに注意してください。ひとつの記事に大量に脚注があったり、そこに重要なことが書いてある場合ユーザー体験を極端に低下させます。重要なことは直接文中に記述するように心がけてください。
そのころわたくしは、モリーオ市の博物局に勤めて居りました。
十八等官 [^1]でしたから役所のなかでも、ずうっと下の方でしたし俸給[^2]もほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。
[^1]: ロシア帝国では、軍隊、政府、および宮廷における地位と階級を**[官等表](https://en.wikipedia.org/wiki/Table_of_Ranks)**と呼ばれるもので管理していました。
[^2]: 役所や会社に務める人の給料のことを指す言葉です。
結果
そのころわたくしは、モリーオ市の博物局に勤めて居りました。 十八等官1 でしたから役所のなかでも、ずうっと下の方でしたし俸給2もほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。
コードブロック
```
で囲むことでコードとして認識され、初めを```言語名
とすることでシンタックスハイライトがつきます。title="タイトル"
とすることでファイル名なども表現できます。また、linenums="1"
とすると行番号を表示できます。
``` csharp title="Program.cs" linenums="1"
using System;
public class Program
{
public static void Main()
{
Console.WriteLine("Hello World!");
}
}
結果
Program.cs | |
---|---|
注意
上記のサンプルでは末尾の```
が欠落しています。(マークダウンの制約)コピペで使用する際はご注意ください。
WSOFTDocsでのリンクのお作法については、コードの埋め込み方を参照してください。
数式
\$\$
で囲むことでTeX記法を用いて数式を記述できます。
$
または\(...\)
で囲むことで、数式を文中に埋め込むこともできます。
ディッフィー・ヘルマン鍵共有プロトコルでは、まず大きな素数 ${\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}\) の値は公開されているものとします。
順序なしリスト
リストの上には空行が必要です。
結果- 文頭に"
*
"、"+
"、"-
"のいずれかを入れると順序なしリストになります - 記号のあとにはスペースが必要です
- 同じリストでは同じ記号を使うことを推奨します。
番号付きリスト
リストの上には空行が必要です。
結果- 文頭に"
数字.
"を入れると番号付きリストになります。 - "
数字.
"のあとにはスペースが必要です - すべての数字を1にすると、自動的に番号が付きます。
タスクリスト
順序なしリストの記述の後ろに[]を入れるとチェックボックスが生成されます。 また、チェックが入った状態のボックスを生成する場合は[x]を入力します。
結果- タスク1
- タスク2
水平線
結果URL
Urlやメールアドレスを書くだけで、自動的にリンクになります。
https://lantana.wsoft.ws
[email protected]
リンク
結果WSOFTDocsでのリンクのお作法については、リンクの使い方を参照してください。
タイトル付きリンク
タイトルはリンクをホバーした時に表示されます。
結果リンクの使いまわし
結果また、linkという書き方もできます。
ボタン
ボタンを使えば、ユーザーにとって注意を引きやすいリンクを作ることができます。ボタンはBootstrapによって提供されているため、クラスを指定するだけで使用できます。次に例を示します。
[ボタン](#){: .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 }
結果
ボタン ボタン ボタン ボタン ボタン ボタン ボタン ボタン ボタン
画像
結果
表
Bootstrapの制約により、ヘッダーでは左右中央揃えが適用されません
| 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を使用することも可能です。
これはネストされた引用です。
図形
Lantanaは規定でmermaid.jsをサポートします。mermaid.jsを使うと、複雑な図形を簡単に挿入できます。
結果
アラート
目を引く形で説明したい場合、!!! 種類 "タイトル"
で囲みます。
メモ
note
で使用できる装飾です。リンクは自動的に適切な色になります。
Abstract
abstract
で使用できる装飾です。リンクは自動的に適切な色になります。
Info
info
で使用できる装飾です。リンクは自動的に適切な色になります。
Tip
tip
で使用できる装飾です。リンクは自動的に適切な色になります。
Success
success
で使用できる装飾です。リンクは自動的に適切な色になります。
Question
question
で使用できる装飾です。リンクは自動的に適切な色になります。
Warning
warning
で使用できる装飾です。リンクは自動的に適切な色になります。
Failure
failure
で使用できる装飾です。リンクは自動的に適切な色になります。
Danger
danger
で使用できる装飾です。リンクは自動的に適切な色になります。
Bug
bug
で使用できる装飾です。リンクは自動的に適切な色になります。
Example
example
で使用できる装飾です。リンクは自動的に適切な色になります。
Quote
quote
で使用できる装飾です。リンクは自動的に適切な色になります。
記事一覧
= "<ディレクトリ名>" =
で囲むと、そのディレクトリの記事一覧を出力します。これはHTMLコード中でも使用できます。
メモ
この機能がLantanaに実装されたことで従来WSOFTDocsに独自に実装されていた、{{ print_thumbnails('') }}
関数は使用されなくなりました。これにより、ビルド時間が150%高速化しました。
スニペットの埋め込み
--8<--
で囲い、その中にファイル名を書き込むと、そのファイルを埋め込みます。
HTMLの埋め込み
HTMLコードは、そのまま記述することで埋め込むことができます。
結果これはHTMLのH4タグです
属性の追加
{: 属性名}
とするとマークダウンで生成される要素に特定の属性を追加できます。
以下のようなHTMLが生成されます