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!");
と記述することでコードをインライン表示できます。
テキストの装飾について詳しく知るには、テキストの書式設定に関する指針を参照してください。
コードブロック
```
で囲むことでコードとして認識され、初めを```言語名
とすることでシンタックスハイライトがつきます。title="タイトル"
とすることでファイル名なども表現できます。また、linenums="1"
とすると行番号を表示できます。
``` csharp title="Program.cs" linenums="1"
using System;
public class Program
{
public static void Main()
{
Console.WriteLine("Hello World!");
}
}
結果
Program.cs | |
---|---|
注意
上記のサンプルでは末尾の```
が欠落しています。(マークダウンの制約)コピペで使用する際はご注意ください。
数式
\$\$
で囲むことで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が生成されます