テクニカルコンテンツの書き方

Image credit: John Moeses Bauan

この記事は、オリジナルテンプレート付属の記事の日本語版です。


このテンプレートは、技術コンテンツの作成者にシームレスな体験を提供するように設計されています。 コンテンツに集中でき、このテンプレートが残りを処理します。(オリジナルテンプレート記事の日本語訳)

コードスニペットの強調表示、数式の描画、テキスト表現からダイアグラムを描画します。

このページでは、このテンプレートでレンダリングできる技術コンテンツをいくつか紹介します。

Examples

Code

このテンプレートは、コードの構文を強調するためのMarkdown拡張機能をサポートしています。 この機能を有効にするには、 config / _default / params.tomlファイルのhighlightオプションを切り替えます。

```python
import pandas as pd
data = pd.read_csv("data.csv")
data.head()
```

renders as

import pandas as pd
data = pd.read_csv("data.csv")
data.head()

Math

このテンプレートは、$ \ LaTeX $数学のMarkdown拡張機能をサポートしています。 この機能を有効にするには、 config / _default / params.tomlファイルのmathオプションを切り替えて、ページフロントマターに markup:mmarkを追加します。

To render inline or block math, wrap your LaTeX math with $$...$$.

Example math block:

$$\gamma_{n} = \frac{ 
\left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T 
\left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}
{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$$

renders as

\[\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}\]

Example inline math $$\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2$$ renders as \(\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2\) .

Example multi-line math using the \\ math linebreak:

$$f(k;p_0^*) = \begin{cases} p_0^* & \text{if }k=1, \\
1-p_0^* & \text {if }k=0.\end{cases}$$

renders as

\[f(k;p_0^*) = \begin{cases} p_0^* & \text{if }k=1, \\ 1-p_0^* & \text {if }k=0.\end{cases}\]

Diagrams

このテンプレートは、図のMarkdown拡張機能をサポートしています。 この機能を有効にするには、 config / _default / params.tomlファイルでdiagramオプションを切り替えるか、ページフロントマターに diagram:trueを追加します。

An example flowchart:

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

renders as

graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;

An example sequence diagram:

```mermaid
sequenceDiagram
  participant Alice
  participant Bob
  Alice->John: Hello John, how are you?
  loop Healthcheck
      John->John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail...
  John-->Alice: Great!
  John->Bob: How about you?
  Bob-->John: Jolly good!
```

renders as

sequenceDiagram
  participant Alice
  participant Bob
  Alice->John: Hello John, how are you?
  loop Healthcheck
      John->John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail...
  John-->Alice: Great!
  John->Bob: How about you?
  Bob-->John: Jolly good!

An example Gantt diagram:

```mermaid
gantt
  dateFormat  YYYY-MM-DD
  section Section
  A task           :a1, 2014-01-01, 30d
  Another task     :after a1  , 20d
  section Another
  Task in sec      :2014-01-12  , 12d
  another task      : 24d
```

renders as

gantt
  dateFormat  YYYY-MM-DD
  section Section
  A task           :a1, 2014-01-01, 30d
  Another task     :after a1  , 20d
  section Another
  Task in sec      :2014-01-12  , 12d
  another task      : 24d

Todo lists

ToDoリストを作成することもできます。

- [x] Write math example
- [x] Write diagram example
- [ ] Do something else

renders as

  • Write math example
  • Write diagram example
  • Do something else

Tables

テーブルでデータを表現:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

renders as

First HeaderSecond Header
Content CellContent Cell
Content CellContent Cell

Asides

このテンプレートは、通知またはヒントとも呼ばれるアサイドのMarkdown拡張機能をサポートしています。 段落の前に A>を付けると、アサイドとして表示されます。 この機能を有効にするには、フロントマターに「markup:mmark」を追加します。または、こちらを使います。Alert shortcode.

A> A Markdown aside is useful for displaying notices, hints, or definitions to your readers.

renders as

このページは役に立ちましたか? よければシェアしてください 🙌

Avatar
Morioffice
翻訳エージェンシー

翻訳コーディネーターが丁寧にヒアリング。不明な点はその都度お聞きします。必要な場合は納品の際、その箇所ごとにコメントをおつけしています。