=== Marklane - Batch Markdown Import for WordPress ===
Contributors: cck23
Tags: markdown, import, importer, frontmatter, mermaid
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Import Markdown into WordPress with post settings, custom fields, batch importing, and Dry Run previews.

== Description ==

Import one or more Markdown files as WordPress posts, including publishing settings from YAML frontmatter. Use Dry Run to inspect the planned changes before creating or updating posts.

**Batch imports:** Import several Markdown files in one operation and review each file's result. A failed import normally does not stop the remaining files.

**Frontmatter:** Set titles, slugs, post types, status, dates, categories, tags, featured images, supported custom fields (`meta`), and terms in existing custom taxonomies (`taxonomies`). Marklane does not create custom field definitions or taxonomies.

**Update posts:** Re-import revised Markdown to update matching posts. Dry Run shows planned actions, taxonomy and image resolution, warnings, and errors without saving.

**Choose how to handle source files:** Markdown selected or dropped locally is not saved in the Media Library. Use **Select from Media Library** to upload and retain a source file. Related images uploaded with Markdown are saved without their original folder structure.

Marklane also supports relative images, Polylang translation links, and optional Mermaid diagrams, callouts, and display math. Markdown without frontmatter can create a draft post.

For setup details and frontmatter examples, see the [Marklane guide](https://happas.jp/en/marklane/).

== Installation ==

1. In the WordPress admin screen, go to `Plugins > Add New`.
2. Search for `Marklane`.
3. Click `Install Now`, then activate the plugin.
4. Open `Tools > Marklane`.
5. Drop one or more local Markdown files into the dropzone or click "Choose files". Use "Select from Media Library" to upload and retain source files in WordPress, or to select existing ones. Locally selected Markdown files are not retained in the Media Library.
6. Run a dry run to preview the result.
7. Run the import to create or update posts, then review the result for each file.

If you prefer manual installation, upload the plugin folder to `/wp-content/plugins/` and activate it from the `Plugins` screen.

== Frequently Asked Questions ==

= Can I import several Markdown files at once? =

Yes. Select multiple `.md` files and run Dry Run or Import. Marklane reports the result for each file. The default limit is 50 Markdown files per request, and each file can be up to 5 MiB.

= What can I set with frontmatter? =

You can set values such as:

* `title`
* `slug`
* `postType`
* `excerpt`
* `status`
* `date`
* `category`
* `tags`
* `meta` (supported custom fields)
* `taxonomies` (existing custom taxonomies)
* `featuredImage`
* `lang`
* `translations`

`postType` defaults to `post`. Public registered post types are allowed by default, except attachments. Site-specific overrides can be applied with the `marklane_whitelist` filter.
If `title` is omitted, Marklane uses the first H1 and then the filename. If `slug` is omitted, Marklane derives it from the filename.

The `meta` field accepts permitted keys with strings, numbers, booleans, or one-dimensional string arrays. The `taxonomies` field assigns terms in existing eligible taxonomies. Marklane does not create custom field definitions or new custom taxonomies.

= Can it update an existing post? =

Yes.

The plugin matches an existing post by `slug + post_type`, or by `slug + post_type + lang` when Polylang is in use.

= What does Dry Run show? =

Dry Run shows the planned action before saving anything, including:

* whether the import will create a new post or update an existing one
* which existing post was matched
* taxonomy assignment results
* relative image and `featuredImage` resolution
* warnings and errors raised during the import

= How are images resolved? =

For a Markdown file selected from Media Library, relative image paths first look for Media Library images in that attachment's directory. Local Markdown imports have no saved Markdown attachment: image resolution uses the expected WordPress uploads location and falls back to matching basenames across uploads and the Media Library.
When Markdown and supporting images are uploaded together, the supporting images are stored as flat Media Library files, so nested folder paths are not preserved.

The `featuredImage` frontmatter field follows the same rule and sets the post thumbnail when the target image is already registered in the Media Library. If [FIFU](https://wordpress.org/plugins/featured-image-from-url/) is active, `featuredImage` can also point to an external URL.

For more predictable results, use fully unique filenames and, if possible, disable WordPress's year/month based upload folders before uploading the Markdown file and related images. This is recommended, not required; basename fallback can still resolve images when year/month folders are enabled.

= Can I enable Japanese strong-emphasis compatibility behavior? =

Yes. Marklane keeps `league/commonmark` as the Markdown converter and uses strict CommonMark behavior by default. If your Japanese writing workflow needs text such as `**「text」**続き` to render as strong text, enable the CJK compatibility pass:

`add_filter('marklane_enable_markdown_compatibility_preprocessing', '__return_true');`

Advanced sites can replace the matching pattern with the `marklane_markdown_compatibility_strong_boundary_pattern` filter. For example, use a custom pattern for Japanese quoted text followed by a letter or number.

= Can it render Mermaid diagrams? =

Yes, optionally.

Enable Mermaid rendering from `Tools > Marklane`, and Marklane will load the bundled Mermaid renderer only on front-end pages that contain `language-mermaid` code blocks. The renderer uses the locally bundled official Mermaid ESM runtime and loads diagram chunks on demand. The post content is still stored as a normal fenced code block, so disabling the option simply returns the front end to plain code blocks.

= Can it render GitHub alerts or Zenn-style callouts? =

Yes, optionally.

Enable Extended Markdown from `Tools > Marklane`, and Marklane will render common callout syntax such as GitHub / Obsidian / GitLab blockquote alerts. Zenn / Docusaurus / Quarto `:::` callouts are normalized during import, then enhanced on the front end. `:::details` is rendered as a native collapsible details element without JavaScript. External embed syntax such as tweets, cards, or videos is not expanded. Advanced sites can limit enabled normalization profiles with the `marklane_extended_markdown_profiles` filter.

= Can it render math formulas? =

Yes, optionally. Enable Math rendering from `Tools > Marklane`, and Marklane will render display formulas written as `$$...$$` only on front-end pages that contain math blocks. Inline math is not expanded. Under the hood, Marklane converts formulas to browser-native MathML with a bundled local renderer.

= Can my theme override these styles? =

Yes. Your theme can customize callouts, Mermaid diagrams, and math blocks using CSS. Callout colors can also be customized with variables such as `--marklane-callout-color-note`.

For styling examples and more information, see the [Marklane official guide](https://happas.jp/en/marklane/).

= Is Marklane free? =

Yes. Marklane is completely free, and all features are available without payment. If you find it useful, you can optionally [support its development on GitHub Sponsors](https://github.com/sponsors/1008k).

= Does it work with Polylang? =

Yes.

When Polylang is active, you can use `lang` and `translations` in frontmatter to connect translated posts.

== Screenshots ==

1. Import screen with Markdown upload, related image selection, post status options, Dry Run, and import controls.

== Changelog ==

= 2.0.0 =
* Import multiple Markdown files at once and review results for each file.
* Import supported custom fields and existing custom taxonomies from frontmatter.
* Improve callout presentation with GitHub Alerts-style callouts and English type labels.
* Update Mermaid to version 12 with revised rendering.
* Reduce distribution size by including only the necessary Mermaid files.
* Update the YAML parser to Symfony 7.4 LTS.
* Minimum requirements changed to WordPress 6.4+ and PHP 8.2+.

= 1.9.0 =
* Add Japanese translations for the admin interface and import results.
* Stop storing Markdown files selected through the dropzone in the Media Library. To retain the original file, open the Media Library with the dedicated button and upload it.
* Simplify admin settings and import result controls.
* Warn about unsupported `meta` fields while importing other content.

= 1.8.0 =
* Add an action to select another Markdown file after an import.
* Move less frequently used options into advanced settings.
* Load Mermaid on demand to reduce initial page loading.

For the complete release history, see the [Marklane changelog](https://happas.jp/en/marklane/changelog/).