コンテンツにスキップ

ベースファイルの作成

English | Français | 한국어 | 日本語

このページでは、ベースファイルを作成する際のルールについて説明します。

概要

MMGはmarkdownファイルやjupyter notebookのmarkdownセルを読み込み、内容を分類します。そのために、MMGは以下の特別なmarkdownコメントを使用します。

  • ヘッダー
    • <!-- multilingual suffix: keyword1, keyword2, keyword3 -->: 今後どのキーワードを使用するかを宣言します。
    • <!-- no suffix: keyword -->: 指定したキーワードのファイルにサフィックスを付けません。
  • マクロ
    • <!-- [[ multilingual toc: level=2~3 ]] -->: 指定した場所に各キーワードの目次を自動生成します。
  • 本文
    • <!-- [keyword] -->: セクションがどのキーワードに属するかを宣言します。
    • <!-- [common] -->: すべての言語で共通する内容を宣言します。
    • <!-- [ignore] -->: セクションを無視します。

Note

MMGのドキュメントでは、「キーワード」と「タグ」の用語を同じ意味で使用しています。 ソースコードでは、変数名suffixまたはlang_tagsとしても呼ばれます。 すべて同じ意味です。

ヘッダー

Note

v2.0.0から、ヘッダーはドキュメントのどこにでも宣言できます。ただし、v1.x.xでは、ヘッダーは本文の前に宣言する必要があります。

使用するキーワードを宣言する

使用するキーワードを宣言します。キーワードはコンマで区切ります。 キーワードにはIETF言語タグを使用できます。

<!-- multilingual suffix: en, kr, fr, es, jp, cn -->

作成されたファイルにサフィックスを付けない（オプション）

作成されたファイルにサフィックスを付けたくない場合は、次のように宣言できます。 たとえば、no suffix: enを設定すると、ファイル名.en.mdは作成されず、ファイル名.mdが作成されます。 GitHubでは、サフィックスが付いているとメインのREADMEが認識されないため、メインのREADMEになるファイルにはno suffixを設定することをお勧めします。

<!-- no suffix: en -->

マクロ

目次マクロ

Baseファイルには、複数のキーワードからのコンテンツが含まれているため、目次を自動生成する既存の方法は機能しません。そのため、MMGは自動的に行うためのマクロを提供しています。

<!-- [[ multilingual toc: level=2~3 ]] -->

レベルオプション

注意事項

  • このlevelオプションは必須です。 levelを省略すると、MMGはこのマクロを通常のコメントとして認識します。
  • 目次マクロは暗黙的に<!-- [common] -->に属するものと見なされます。そのため、目次マクロを使用すると、自動的に現在のキーワードがcommonに変更されます。

levelを表示する方法は4つあります。

  • level=2: レベル2の見出しだけが目次に表示されます。
  • level=2~: レベル2から9の見出しが目次に表示されます。
  • level=~4: レベル1から4の見出しが目次に表示されます。
  • level=2~4: レベル2から4の見出しが目次に表示されます。

絵文字なしオプション

時には、タイトルに絵文字を入れながら、目次では絵文字を消したい場合があります。 あなたがこのような状況であれば、以下のように no-emojiオプションを適用してください。

<!-- [[ multilingual toc: level=2~3 no-emoji ]] -->

no-emojiが適用されると、絵文字のないタイトルのみが目次に表示されます。

**Table of Contents**

1. [Heading 1](#heading-1-)
2. [Heading 2](#heading-2-)

# Heading 1 💎
# Heading 2 ❤️

**Table of Contents**

1. [Heading 1 💎](#heading-1-)
2. [Heading 2 ❤️](#heading-2-)

# Heading 1 💎
# Heading 2 ❤️

アンカーオプション

見出しアンカーは標準化されておらず、レンダラーごとに見出しIDの生成規則が異なります。 MMGは既定でGitHub形式のアンカーを生成し、これは.mdでも.ipynbでもGitHub上で正しく動作します。 一方、Jupyter・nbconvert・Colabは見出しの大文字小文字と句読点をそのまま保持するため、GitHub向けに生成した目次はこれらのビューアーではリンクが移動しません。 anchorオプションで、どのレンダラーを対象にするかを選べます。

<!-- [[ multilingual toc: level=2~3, anchor=jupyter ]] -->
  • anchor=github（既定値）: # Nombre d'étoiles は #nombre-détoiles になります。小文字化し、句読点と絵文字を削除し、見出しが重複すると -1、-2 のように番号が付きます。
  • anchor=jupyter: # Nombre d'étoiles は #Nombre-d'%C3%A9toiles になります。大文字小文字・句読点・絵文字をそのまま保持し、ASCII 以外の文字はパーセントエンコードされ、見出しが重複してもアンカーは同じままです。Jupyter 自体がそう動作するためです。

注意事項

  • 既定値はgithubです。生成したファイルをJupyter系のビューアーで読む場合にのみanchor=jupyterを選んでください。同じアンカーはGitHubでは移動しません。
  • 不明な値は検証時に拒否されます。githubとjupyterのみ、小文字で指定できます。

本文

キーワードが認識されると、その後のコンテンツは、別のキーワードが表示されるまで、そのキーワードで認識されます。

ユーザー定義キーワード

ヘッダーで宣言されたキーワードを使用して、セクションがどのキーワードに属するかを宣言できます。 誤って未定義のキーワードを使用した場合や、キーワードの数が一致しない場合は、検証機能を介してエラーが通知されます。

<!-- [en] -->
<!-- [ko] -->
<!-- [fr] -->
<!-- [es] -->
<!-- [ja] -->
<!-- [cn] -->
...

共通セクション

生成されるすべてのファイルに共通する内容を宣言できます。

<!-- [common] -->
この内容はすべてのファイルに表示されます。

無視されるセクション

コメントやメモなど、作成されたファイルから除外したいセクションがある場合は、ignoreキーワードを使用します。

<!-- [ignore] -->
このセクションは、作成されたファイルに含まれません。