Skip to content

migrate.md

Latest commit

 

History

History
165 lines (117 loc) · 4.56 KB

migrate.md

File metadata and controls

165 lines (117 loc) · 4.56 KB

mdpress migrate

中文说明

Purpose

Convert a GitBook or HonKit project to mdPress format. The migrate command detects GitBook/HonKit structure, converts book.json to book.yaml, rewrites GitBook-specific template tags in Markdown files, and prints a migration report.

Syntax

mdpress migrate [directory] [flags]

Positional Arguments

Argument Required Description
[directory] No Path to the GitBook/HonKit project. If omitted, the current directory is used.

Flags

Flag Default Description
--dry-run off Preview changes without writing any files. Useful for checking what will be modified before committing to the migration.
--force off Overwrite existing book.yaml instead of skipping.

Behavior

Detection

migrate checks for GitBook/HonKit project markers in the directory:

  • book.json: GitBook/HonKit configuration file
  • SUMMARY.md: GitBook chapter structure (already compatible with mdPress)

If neither file is found, the command fails with an error.

Conversion Steps

  1. Reads book.json (if present)

    • Parses JSON configuration
    • Extracts title, author, language, and description
    • Converts to book.yaml format with mdPress structure
    • Adds a comment header: # Generated by mdpress migrate from book.json

  2. Skips SUMMARY.md

    • mdPress natively supports GitBook-style SUMMARY.md
    • No conversion needed; the file is left untouched

  3. Rewrites GitBook template tags in Markdown files

    • {% hint style="TYPE" %}...{% endhint %} → Markdown blockquote with type prefix
    • {% code title="..." %}...{% endcode %} → Fenced code block (title is dropped)
    • {% tabs %}...{% endtabs %} with nested {% tab title="NAME" %} → Level 4 headings (####) plus content

  4. Walks all .md files recursively

    • Skips hidden directories (starting with .), node_modules/, and _book/
    • Only processes .md files with recognized GitBook tags
    • Writes modified files in place (unless --dry-run is set)

  5. Prints a migration report

    • Lists created files (e.g., book.yaml)
    • Lists modified files (Markdown files with rewritten tags)
    • Lists skipped items (e.g., SUMMARY.md)
    • Lists warnings (e.g., unsupported plugins)

Dry-Run Mode

When --dry-run is set:

mdpress migrate --dry-run ./my-gitbook

The command prints what it would do without modifying any files. Useful for previewing the impact before committing to the migration.

GitBook Plugin Warnings

The command reads book.json and warns about plugins that have no direct mdPress equivalent:

Warnings:
  ! GitBook plugin "disqus" has no direct mdpress equivalent — you may need to manually implement equivalent features

Known plugins that are handled natively or skipped:

  • highlight, search, lunr, sharing, fontsettings, theme-default

Examples

# Migrate the current directory
mdpress migrate

# Migrate a specific GitBook project
mdpress migrate ./my-gitbook

# Preview changes without writing
mdpress migrate --dry-run ./my-gitbook

# Migrate and then build
mdpress migrate ./my-gitbook
mdpress build ./my-gitbook --format pdf

Output

Generated Files

When book.json exists, the command creates book.yaml:

# Generated by `mdpress migrate` from book.json
# Review and adjust as needed.

book:
  title: My Book
  author: John Doe
  language: en
  description: A sample book
style:
  theme: technical
output:
  filename: output
  toc: true
  cover: false

Modified Files

Markdown files are rewritten in place to use standard Markdown equivalents:

Before (GitBook):

{% hint style="info" %}
This is important.
{% endhint %}

{% code title="example.sh" %}
echo "Hello"
{% endcode %}

After (mdPress):

> **INFO:** This is important.

echo "Hello"

Notes

  • The command is best used as the first step after cloning a GitBook project.
  • Always review the generated book.yaml and ensure it matches your intended metadata.
  • GitBook plugins that have no mdPress equivalent will generate warnings; you may need to manually implement equivalent features.
  • After migration, run mdpress validate to check the resulting structure.
  • Run mdpress build to generate the output in your preferred format.

See Also