Skip to content

Create a Base File

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

This page describes the rules for creating a base file.

Summary

MMG reads markdown files or markdown cells in jupyter notebook and classifies the contents. To do this, MMG uses the following special markdown comments.

  • Header
    • <!-- multilingual suffix: keyword1, keyword2, keyword3 -->: Declare which keywords to use in the future.
    • <!-- no suffix: keyword -->: Do not append suffix to the created file for the specified keyword.
  • Macro
    • <!-- [[ multilingual toc: level=2~3 ]] -->: Automatically generate a table of contents for each keyword at the specified location.
  • Body
    • <!-- [keyword] -->: Declare which keyword the section belongs to.
    • <!-- [common] -->: Declare the content that will be common to all languages.
    • <!-- [ignore] -->: Ignore the section.

Note

In MMG documents, the terms 'keyword' and 'tag' are used interchangeably. In the source code, it is also called as variable name suffix or lang_tags. They all mean the same thing.

Note

Starting from v2.0.0, headers can be declared anywhere in the document. However, in v1.x.x, headers must be declared before the body starts.

Declare Keywords to Use

Declare the keywords to use. Keywords are separated by commas. You can use IETF language tags for keywords.

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

Do Not Append Suffix to the Created File (Optional)

If you do not want to append a suffix to the created file, you can declare it as follows. For example, if you set no suffix: en, filename.en.md will not be created, but filename.md will be created. In GitHub, the main README is not recognized if a suffix is attached, so it is recommended to set no suffix for the file to be the main README.

<!-- no suffix: en -->

Macro

Table of Contents Macro

Existing methods for generating a table of contents don't work for base files with content from multiple keywords. That's why MMG provides a macro to do it automatically.

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

Level Option

Cautions

  • The level option is required. If you omit level, MMG will treat this macro as a normal comment.
  • The table of contents macro is implicitly assumed to belong to <!-- [common] -->. So, when you use the table of contents macro, the current keyword is automatically changed to common.

There are four ways to specify the level to display.

  • level=2: Only level 2 headings are displayed in the table of contents.
  • level=2~: Level 2 to 9 headings are displayed in the table of contents.
  • level=~4: Level 1 to 4 headings are displayed in the table of contents.
  • level=2~4: Level 2 to 4 headings are displayed in the table of contents.

No-Emoji Option

Sometimes you may want to add emoticons to the title but delete them from the table of contents. If you are in this situation, apply the no-emoji option as shown below.

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

If no-emoji is applied, only titles without emojis will be displayed in the table of contents.

**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 ❤️

Body

Once a keyword is recognized, subsequent content will be recognized with that keyword until another keyword appears.

User-Defined Keyword

Using the keywords declared in the header, you can declare which keyword the section belongs to. If you use an undefined keyword by mistake or the number of keywords does not match, MMG will notify you of an error through the validation feature.

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

Common Section

You can declare the content that will be common to all languages.

<!-- [common] -->
This content will be shown in all files.

Ignored Section

Sometimes you may want to ignore a section, such as comments or minor memos, from the created file. In that case, use the ignore keyword.

<!-- [ignore] -->
This section will not be included in the created file.