Codatum CLI

Appearance

ドキュメントページ ​

概要 ​

  • ノートブックファイル内のドキュメントページでは、通常のマークダウン形式のドキュメントに加えて、SQLブロックやチャートといった特殊なブロックを記述できます
  • ドキュメントページは以下の構造により記述します
    • yaml {.page} によるページ属性
    • マークダウン形式によるページ本文

ページ属性 ​

  • ページ属性は yaml {.page} のコードブロックとして次のオブジェクト型で表現します
    • id はノートブックファイル内でユニークな値を指定します
      • 未指定の場合、 format 実行時に自動付与されます
    • width にはページ幅を指定します
      • デフォルトは { width_type: 'RANGE', max_width: 800 } で、最大800pxまで伸縮します
    • パラメータに関する説明は パラメータ を参照してください
ts
type DocPageAttrs = {
  type: 'DOC_PAGE';
  id: ObjectId;
  width?:
    | { width_type: 'AUTO' }
    | { width_type: 'FIXED'; fixed_width: 640 | 800 | 1024 | 1280 | 1366 | 1600 }
    | {
        width_type: 'RANGE';
        min_width?: 640 | 800 | 1024 | 1280 | 1366 | 1600;
        max_width?: 640 | 800 | 1024 | 1280 | 1366 | 1600;
      };

  // パラメータの説明を参照
  notebook_param_widget_values?: ParamWidgetValue[];
  page_param_widgets?: ParamWidget[];
  page_param_widget_values?: ParamWidgetValue[];
};

固有表現 ​

ドキュメントページでは、通常のマークダウン形式のドキュメント以外に加えて、以下の固有な表現が利用できます

空パラグラフ ​

マークダウンでは空行はブロック区切りとして扱われるため、空のパラグラフをそのまま表現できません。そのため、空のパラグラフを明示的に表現する場合は次のように記述します。

  • ::p リーフディレクティブを使って記述します
    • ラベルや属性は指定できません

例 ​

md
::p

折りたたみリスト ​

  • クリックで開閉可能なリストアイテムを記述する場合は、箇条書きの先頭に > を付けて記述します
  • 折りたたみリスト（トグルリスト）の中身は1つのパラグラフのみ指定できます

例 ​

md
- > クリックで開閉できる項目
  - 子要素1
  - 子要素2
- 通常の項目

SQLブロック ​

  • :::sql-block コンテナディレクティブを使って記述します
  • 詳細については SQLブロック を参照してください

チャートブロック ​

  • 以下のオブジェクトを yaml {.chart} のコードブロックとして記述します
    • id はページ内でユニークな値を指定します
      • 未指定の場合は、 format を実行すると自動挿入されます
    • sqlId はデータソースとするSQLブロックの id を指定します
      • SQLブロック内でチャートを定義する場合は、 sqlId は不要ですが、SQLブロック外でチャートを定義する場合は必須です
    • height はチャートの高さを指定します（未指定の場合は 300px）
    • chartSettings にはチャートの設定を指定します。詳細は チャート を参照
  • chartJobId には、チャート用のデータ加工に利用されたジョブのジョブリソースIDが付与されます
ts
type BlockChart = {
  id: ObjectId;
  sqlId: ObjectId;
  chartSettings: ChartSettings;
  height?: string;

  // 以下は実行時に自動的に付与される
  chartJobId?: JobResourceId;
  chartJobQueryHash?: string;
};

例 ​

md
```yaml {.chart}
id: 69cafa6c871431229e5a3fe1
sqlId: 69ddc377379170547e659978
chartSettings:
  template_type: RADIAL_CHART_V2
  component_settings:
    render_type: PIE
    x:
      - field: category
    ys:
      - field: sales
        aggregator: SUM      
```

インラインチャート ​

  • チャートをインライン要素として記述する場合は、インラインチャートを利用します
    • インラインチャートはパラグラフ内に記述することができ、リストやテーブル内にもチャートを配置できるようになります
  • インラインチャートは、同じページ内に参照（:inline-chart-refテキストディレクティブ）と定義（yaml {.inline-chart-def}コードブロック）を分けて記述します
    • 定義: チャートブロックと同様のチャート定義を記述します
      • ただし、 id は省略できず、ページ内でユニークな値を指定する必要があります
    • 参照: 定義の id を chartId 属性に指定します（ラベルは不要）
    • 参照とチャート定義は必ず1対1に対応する必要があり、複数の参照に対応するチャート定義を記述することはできません
    • 定義は参照と同じページ内であれば、任意の場所に記述できます
      • format を実行すると、参照を含んだルート直下のブロックの直後に定義が出力されます。カラムレイアウトやテキストテーブルのようなコンテナ内に参照がある場合は、そのコンテナの直後にまとめて出力されます
      • 対応する参照がない定義は、 validate 実行時にはエラーに、 format 実行時には自動削除されます

例 ​

md
- 今月のサマリ
  - 売上推移 :inline-chart-ref{chartId="69cafa6c871431229e5a3fe1"}
  - 販売数推移 :inline-chart-ref{chartId="69cafa6c871431229e5a3fe2"}

```yaml {.inline-chart-def}
id: 69cafa6c871431229e5a3fe1
sqlId: 69ddc377379170547e659978
chartSettings:
  template_type: XY_CHART_V2
  component_settings:
    # 省略
```

```yaml {.inline-chart-def}
id: 69cafa6c871431229e5a3fe2
sqlId: 69ddc377379170547e659979
chartSettings:
  template_type: XY_CHART_V2
  component_settings:
    # 省略
```

テーブルビューア ​

  • DWHのテーブルのプレビューをページ内に埋め込んで表示します
  • 以下のオブジェクトを yaml {.table-viewer} のコードブロックとして記述します
    • tableResourceId はテーブルリソースIDを指定します
      • テーブルリソースIDの形式についてはリソースIDを参照してください
    • maxRows は表示する最大行数を指定します（未指定の場合は 20）
    • height はテーブルの高さを指定します（未指定の場合は 300px）
ts
type TableView = {
  tableResourceId: TableResourceId;
  maxRows?: 20 | 100 | 1000;
  height?: string;
};

例 ​

md
```yaml {.table-viewer}
tableResourceId: bq/cn=69cafa6c871431229e5a3fe1/pj=bigquery-public-data/ds=austin_bikeshare/tb=stations
maxRows: 100
```

スカラ値参照 ​

  • ドキュメント内にSQLブロックの実行結果をインライン要素として埋め込む際に利用します
    • 実行結果の1行目の指定したカラムの値を表示します
  • テキストディレクティブ :sql-result-scalar に以下の属性を指定します（ラベルは不要）
    • resultScalarId: ObjectId はページ内でユニークな値を指定します
      • 未指定の場合は、 format を実行すると自動挿入されます
    • sqlId: ObjectId は同じページ内にあるSQLブロックの id を指定します（必須）
    • field: string はSQLブロックの実行結果のカラム名を指定します（必須）

例 ​

md

今月の売上は :sql-result-scalar{resultScalarId="69f14c079d22440d1c126076" sqlId="69f0976865b560bb46ce8d10" field="sales_amount"} 円でした。

ダイアグラムブロック ​

  • コードブロックの言語に mermaid を指定すると、ダイアグラムブロックとして表示されます

例 ​

md
```mermaid
flowchart TD
  A[Start] --> B{Is it?}
  B -- Yes --> C[OK]
  C --> D[Rethink]
  D --> B
  B -- No ----> E[End]
```

数式ブロック・インライン数式 ​

  • コードブロックの言語に math を指定すると、数式ブロックとして表示されます
  • インラインで数式を記述する場合は、 :math テキストディレクティブを使って記述します
    • :math[e = mc^2] のようにラベルに表示する数式を指定します
  • 数式の記法については KaTeXの公式ドキュメント を参照してください

例 ​

md
```math
E = mc^2
```

質量とエネルギーの等価性を示す :math[E = mc^2] は有名な数式です。

コールアウトブロック ​

  • :::callout-xxx コンテナディレクティブを使って記述します
    • xxx には info / success / warn / danger のいずれかを指定します
  • :::callout-xxx の中には、パラグラフ、リストのみが記述できます
  • アイコンを指定する場合は :::callout-xxx{icon="😊"} のように指定します

例 ​

md
:::callout-info
パラグラフ

- 箇条書き1
- 箇条書き2
:::

:::callout-warn{icon="🔔"}
警告メッセージ
:::

カラムレイアウト ​

  • カラムレイアウトは、ドキュメントページ内で2つ以上のカラムを配置するためのレイアウトブロックです
  • カラムレイアウトでは、 ::::columns の中に、2つ以上の :::column を配置します
    • 親の ::::columns は : が4つとなる点に注意してください
  • :::column の中には、パラグラフ、リスト、チャートのみが記述できます（SQLブロック等のブロック要素は記述できません）

例 ​

md
::::columns
:::column
左カラムの内容
:::

:::column
右カラムの内容
:::
::::

テキストテーブル ​

  • ドキュメントページでは、GFM Table を利用可能ですが、セル内に複数のパラグラフやリスト等を記述するための固有表現として、テキストテーブルを利用できます
  • テキストテーブルでは、 :::::text-table のコンテナディレクティブを使って記述します
    • 親の :::::text-table は : が5つ、 ::::row は4つとなる点に注意してください
    • :::::text-table の中には、 ::::row を1つ以上配置します
    • ::::row の中には、 :::cell もしくは :::header-cell を1つ以上配置します
    • :::cell および :::header-cell の中には、パラグラフ、リストのみが記述できます
  • セル結合や列幅指定を行う場合は、 :::cell または :::header-cell に以下の属性を指定します（いずれも省略可）
    • colspan: number は列方向のセル結合数を指定します（デフォルト 1）
    • rowspan: number は行方向のセル結合数を指定します（デフォルト 1）
    • colwidth: string はセルの列幅をカンマ区切りで指定します（例: colwidth="120,80"）
  • GFM Table で表現可能なテーブルは、 format 実行時に GFM Table へ正規化されます
    • 以下のいずれかに該当する場合は :::::text-table のままとなります
      • セル内にリストや複数のパラグラフが含まれる
      • colspan / rowspan が 2 以上のセルが存在する
      • colwidth が指定されている
      • 1行目以外にヘッダーセルが存在する、または1行目にヘッダーセル以外が混在する

例: セル内にリストを含む ​

md
:::::text-table
::::row
:::header-cell
項目
:::
:::header-cell
詳細
:::
::::
::::row
:::cell
タスク
:::
:::cell
- 設計
- 実装
- テスト
:::
::::
:::::

例: セル結合と列幅指定 ​

md
:::::text-table
::::row
:::header-cell{colspan=2 colwidth="120,200"}
グループA
:::
:::header-cell
備考
:::
::::
::::row
:::cell
左
:::
:::cell
中央
:::
:::cell{rowspan=2}
共通備考
:::
::::
::::row
:::cell{colspan=2}
結合された行
:::
::::
:::::

その他の固有表現 ​

以下の固有表現は、Web版ノートブック 専用の機能に起因する表現です。中身を編集したり、新規に作成したりするのは避けてください。

  • テキストディレクティブ
    • :image: 画像埋め込み
    • :video: 動画埋め込み
    • :notebook-link: ノートブック間のリンク
    • :mention: メンション
  • 特殊なコードブロック
    • yaml {.oembed}: 埋め込みブロック

利用可能な拡張記法 ​

ドキュメントページ内では以下の拡張記法が利用可能できます。

マークダウン記法の制限 ​

ドキュメントページ内では一部のマークダウン記法に表現上の制限があります。

リスト ​

  • 箇条書き(ul)、順序付き箇条書き(ol)、タスクリスト(GFM拡張)、折りたたみリストでは、1つのリストアイテムに対して1つのパラグラフしか指定できません
    • 複数の子パラグラフを持つリストアイテムは記述できません
    • パラグラフ以外の子要素を持つリストアイテムは記述できません

引用ブロック ​

  • 引用ブロック(blockquote)の内部には、パラグラフとリストのみが指定できます
    • その他のブロック要素は記述できません
    • 引用ブロックのネストもできません