Codatum CLI

Appearance

ノートブックファイル ​

概要 ​

  • .cnb.md の拡張子を持つマークダウンファイルをノートブックファイルと呼びます
  • ノートブックファイルは、フロントマターと本文から構成され、本文は h1（見出し1） を挟むことで、複数のページを持つことができます

フォーマット ​

ノートブックファイルは、以下の拡張を含むマークダウン形式で記述します。

  • フロントマター(YAML)
  • ディレクティブ拡張
  • コードブロックの属性指定

以下の拡張・表現には対応していません。

  • HTMLタグ

ディレクティブ拡張 ​

mdast-util-directive の拡張表現を利用します。

コンテナディレクティブ ​

  • :::name{key=value key2=value2} と ::: で囲まれた範囲を1つのブロックとして扱います
    • ブロック内には他のマークダウン要素を記述できます
    • ブロック内に記述可能なマークダウン要素や属性は name ごとに異なります
    • 属性は { と } で囲まれた部分に、key=value の形式で指定します
      • 属性は必須ではなく、指定不要な場合もあります
    • コンテナディレクティブをネストさせる場合、 ::::parent, :::child のように、親ディレクティブの : の数を増やして記述します
md
:::name
content
:::

リーフディレクティブ ​

  • ::name[label]{key=value key2=value2} の形式でブロック要素を記述します
    • name ごとにラベルや属性の定義が異なります
    • ラベルや属性は必須ではなく、指定不要な場合もあります
  • 例えば、空のパラグラフは次のように記述します
md
::p

テキストディレクティブ ​

  • :name[label]{key=value key2=value2} の形式でインライン要素を記述します

コードブロックの属性指定 ​

  • コードブロックで、言語名に続いて {.class} の形式でクラス名を指定可能です
    • 言語名と { の間には半角スペースを挟む必要があります
md
```yaml {.class1}
key: value
```

構成 ​

フロントマター ​

  • ノートブックの属性情報をフロントマターで記述します
  • フロントマターはYAML形式で記述し、以下のオブジェクト型で表現します
    • TOMLやJSONでの記述には非対応です
    • パラメータに関する説明は パラメータ を参照してください
  • id や workspace_id は、Codatum のサービス側で生成・指定されるIDです
    • 必ずcdm notebookのコマンド経由で取得・生成してください
ts
type NotebookMetadata = {
  type: "CODATUM_NOTEBOOK";
  id: ObjectId;
  workspace_id: ObjectId;
  name: string;
  icon?: string;

  notebook_param_widgets?: ParamWidget[];
};

例 ​

md
---
type: CODATUM_NOTEBOOK
id: 671ef14b0d08cf6c657df7da
workspace_id: 6653ebab5a1acaa5bd5422a5
name: "My Notebook"
icon: "🚀"
---

ページの記述方法 ​

  • 本文内の h1（見出し1） をページの区切りとして扱います
    • ページ内で見出し要素を使う場合は、 h2 - h4（見出し2〜4） を使用してください
  • 各ページは h1 の直後に yaml {.page} のコードブロックを持ち、その中でページ属性を指定します
    • type にはページの種類を指定します
    • id にはノートブックファイル内でユニークな値を指定します
      • 未指定の場合、 format 実行時に自動付与されます

例 ​

md
---
type: CODATUM_NOTEBOOK
id: 671ef14b0d08cf6c657df7da
workspace_id: 6653ebab5a1acaa5bd5422a5
name: My Notebook
---

# page1

```yaml {.page}
type: DOC_PAGE
id: 66a75e5c3a1402e7954373ca
```

（page1本文）

# page2

```yaml {.page}
type: GRID_PAGE
id: 66a75e5c3a1402e7954373cb
```

（page2本文）

ページの種類 ​

ドキュメントページ ​

  • ドキュメントページには、SQLブロックやチャート定義、またそれらの説明を記述できます
  • ページ属性には type: DOC_PAGE を指定します
    • format を実行するとページ属性が定義されていないページはドキュメントページとして扱われ、ドキュメントページの属性が挿入されます
  • ページ属性に続いて、ドキュメントの本文をマークダウン形式で記述します
    • 通常のマークダウンドキュメントに加えて、SQLブロックやチャート定義といった特殊なブロックを記述できます
  • 詳細については、ドキュメントページ を参照してください

例 ​

md
# ドキュメントページサンプル

```yaml {.page}
type: DOC_PAGE
id: 66a75e5c3a1402e7954373ca
```

## 見出し2
### 見出し3
#### 見出し4

ドキュメントの記述例

- 箇条書き1
- 箇条書き2
- 箇条書き3

グリッドページ ​

  • グリッドページでは、ドキュメントページで定義したSQLブロックの実行結果やチャートを、ダッシュボードとしてレイアウトする役割を担います
  • ページ属性には type: GRID_PAGE を指定します
  • ページ属性に続いて、グリッド内に配置するグリッド要素をコンテナディレクティブ :::grid-item で記述します
  • ページの最後に、グリッド要素のレイアウトを yaml {.grid-layout} のコードブロックで記述します

例 ​

md
# グリッドページサンプル

```yaml {.page}
type: GRID_PAGE
id: 66a75e5c3a1402e7954373cb
```

:::grid-item
```yaml {.attrs}
type: HEADING
id: 69dac8455174dcb50b75eec1
description: Example Description
```

## Example Heading
:::

:::grid-item
```yaml {.attrs}
type: CHART
id: 69dac8455174dcb50b75eec3
pageId: 69dac8455174dcb50b75eec1
chartId: 69dac8455174dcb50b75eec2
name: Example Chart
```
:::

```yaml {.grid-layout}
- type: columns
  children:
    - type: leaf
      ref: 69dac8455174dcb50b75eec1
      height: 4
      width: 6
    - type: leaf
      ref: 69dac8455174dcb50b75eec3
      height: 4
      width: 6
```

区切りページ ​

  • 区切りページはページ本文を持たず、ページ一覧に区切りラベルを挿入するためだけに利用されます
  • ページ属性には type: DIVIDER を指定します

例 ​

以下の内容を「ダッシュボード」ページと「用語集」ページの間に挿入することで、ページ一覧の「ダッシュボード」と「用語集」の間に「付録」というラベルが表示されます。

md
# 付録

```yaml {.page}
type: DIVIDER
id: 66a75e5c3a1402e7954373cc
```