Table of Contents ⚡

1. Overview
   1. How It Works
   2. Features
2. Installation
   1. Linux
   2. macOS
   3. Windows
3. How to Use
4. Troubleshooting
5. Changelog
6. Contributors

Overview 🔎

How It Works

By managing only one Base file, we can reduce the number of errors caused by missing or mismatched translations. Additionally, thanks to editing in a single file, we can expect convenient translation with the auto-completion function of AI tools such as Copilot.

Markdown:

Jupyter Notebook:

Features

Supports the following features:

• Markdown, Jupyter Notebook(.ipynb) as input formats
• As-is, HTML, PDF as ouput formats
• Command-line interface for Bash, Zsh, Windows PowerShell
• Python API
• Recursive traversal mode with -r option (As-is, HTML, PDF are all supported)
• Batch processing mode with YAML file (Only As-is is supported)
• IETF language tags
• UTF-8 encoding
• Automatic generation of table of contents with level and emoji options (Markdown and Jupyter Notebook are both supported)
• Base file validation (Check the number of tags of each language)
• Validation only mode for CI/CD (Disable file generation)

Installation 📦

Linux

pip3 install mmg

macOS

pip3 install mmg

If you have any issues with WeasyPrint, install it with the following command. WeasyPrint is only used to create PDFs.

brew install weasyprint

Windows

Python is not installed by default on Windows. Please install Python first, then install MMG using the Python package manager pip.

pip3 install mmg

If you installed Python from the Microsoft Store, you may see the following warning when installing MMG. (The displayed path may vary for each user.)

$ pip3 install mmg
...
  WARNING: The script mmg.exe is installed in 'C:\Users\...\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\LocalCache\local-packages\Python311\Scripts' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed mmg-2.0.1

If you see this warning, it means the mmg command cannot be found in the terminal. Please add the path shown in the warning message to the PATH environment variable. Instructions for adding to PATH can be found in the Troubleshooting documentation.

Additionally, MMG uses WeasyPrint to create PDFs. WeasyPrint requires the GTK library, so download and run the latest GTK3 installer. If you are not interested in creating PDFs, you can skip this step. Other features of MMG are available without GTK.

How to Use 💡

Please refer to the documentation for detailed usage and examples.

$ mmg --help
Usage: mmg [OPTIONS] [FILE_NAMES]...

  FILE_NAMES: Base file names to convert.

  Supported extensions are:
      .md, .markdown, .mkd (Markdown)
      .mdx (MDX - Markdown + JSX) [experimental]
      .rmd (R Markdown) [experimental]
      .mmd (MultiMarkdown) [experimental]
      .qmd (Quarto) [experimental]
      .ipynb (Jupyter Notebook)

  Here are some examples:
      mmg *.base.md
      mmg *.base.ipynb
      mmg *.base.md *.base.ipynb -o pdf --css github-dark
      mmg --recursive
      mmg --recursive --validation-only
      mmg --batch mmg.yml

Options:
  -r, --recursive                 This will search all subfolders based on
                                  current directory.
  -b, --batch FILE                YAML file path for batch conversion.
                                  (Default: None)
  -o, --output-format [as-is|html|pdf]
                                  Output format. (Default: as-is)
  --css TEXT                      CSS file path or preset('github-
                                  light'/'github-dark'). Only for the HTML/PDF
                                  output. (Default: github-light)
  -y, --yes                       This will confirm the conversion without
                                  asking. (Default: False)
  -s, --skip-validation           Skip the health check. (Default: False)
  --validation-only               Only check the health. (Default: False)
  -v, --verbose                   Verbosity level from 0 to 2. --verbose:1,
                                  -v:1, -vv:2 (Default: 0)
  --version                       Show the current version.
  --help                          Show this message and exit.

Troubleshooting 💊

Please refer to the troubleshooting page on the website.

Changelog 📝

CHANGELOG.md

Contributors 🤝

Made with contrib.rocks.

If you are interested in how to contribute, please refer to the contribution guide.