The importer is available in b2evolution 7.0.1+ but some advanced features are only available in b2evolution PRO.

The Markdown importer allows you to import a directory structure containing MarkDown .md files + related images.

Basic Concepts

Slugs Extracted from Filenames

A file like xyz.md will generate an Item, using the slug xyz (or, if not available, xyz-1, xyz-2, etc.)

Image References

If the .md file references an image like ![Alt Text](assets/image.png), it will be imported to quick-uploads/xyz/image.png and referenced with a b2evolution [image:] Short Tag and linked as inline if the image is located in Item’s content after first header or when content has no header, otherwise the image will be linked as teaser without referenced [image:] Short Tag. The alt text will be attached to the Image File in the DB.

Links to Other Pages

If the .md file references another .md file with a link like [Link title](folder/subfolder/Destination-Page.md), it will be converted to a b2evolution Short Link like ((destination-page Link title)).

Import Tool

List of Potential Files to be Imported

This shows the folders and ZIP files found in /media/import/.

Select the radio button in front of the directory or ZIP file that you want to import.

If you select a ZIP file it will be decompressed into a temporary directory and the contents will be imported as if you had selected a directory. On successful import, the temporary directory will be deleted.

You can upload additional files to import or delete old files by clicking on Upload/Manage import files.

Destination collection:

Select the collection where the Items matching the .md files should be created.

Import mode:

Select how you would like to import the contents of .md files into your collection:

1. Update existing contents
   This will keep any existing Items and try to update them by matching the slug name. This is particularly useful if you are using your .md files as the "source of truth" and import them regularly to update the content in b2evolution. In that case b2evolution hold a "mirror" of the content of your .md files.

   • A file like xyz.md will update an Item with slug xyz in the same collection (or, if not found, xyz-1, xyz-2, etc.)
   • If not found, a new Item will be created.
   • If the content has changed (based on an MD5 hash from previous import), the new content will replace the previous, and the previous content will be saved in the Item’s Change History.
   • If the location of the xyz.md file has changed in the directory structure, the Item’s main Category/Chapter will be updated accordingly.

   Regarding images:

   • Any identical image on the system (based on MD5 hash) will be re-used.
   • If an image with the same filename is attached to the Item but the MD5 hash doesn’t match, the image will be replaced on disk.
   • Otherwise a new image file will be created.

2. Append to existing contents

   Nothing of what’s already in the DB or disk will be re-used. This is useful if you know you are importing new content and you don’t want it to interfere with existing content.

   • A file like xyz.md will create an Item with slug xyz (or, if it already exists: xyz-1, xyz-2, etc.)
   • An image like xyz.png will create a media file like xyz.png (or, if it already exists: xyz-1.png, xyz-2.png, etc.)

   Additional options:

   • Reuse existing categories : in that case the importer will interfere with your existing content, but only as far as adding posts into existing categories (based on folder name = slug name).

3. Replace existing contents

   This will first delete all Items (and related DB contents) from the collection and then (re-)import your contents. This is useful if you know all content is clean in your .md files while the content of your site are broken.

   A file like xyz.md will generate an Item, using the slug xyz (or, if not available, xyz-1, xyz-2, etc.)

   Additional options:

   • Also delete media files that will no longer be referenced in the destination collection after replacing its contents will also delete images (or other media files) if they are not referenced in the new import.

Options:

• Convert Markdown relative links to b2evolution ShortLinks: check to convert a MarkDown link like [Link title](folder/subfolder/Destination-Page.md) to a b2evolution Short Link like ((destination-page Link title))

  Several sub options are available in this case:

  • Check all internal links (slugs) to see if they link to a page of the same language (if not, log a Warning)
    • If different language, use the "linked languages/versions" table to find the equivalent in the same language (and log the suggestion)
      • If a same language match was found, replace the link slug in the post while importing
      • If a same language match was found, replace the link slug in the original .md file on disk so it doesn’t trigger warnings next time (and can be versioned into Git). This requires using a directory to import, not a ZIP file.

  If all the above are checked, b2evolution will update your source .md markdown files. This is useful if you are using .md files as the "source of truth" for your content.

• Force Item update, even if file hash has not changed: check to update item content even if the file hash is same from the last import.

• PRO Once import is done, delete all categories that do not/no longer contain any posts.: performs a recursive swipe to find categories no longer used, in case of heavy reorganization of the file / category structure.

Use of YAML Meta Data

The import tool recognizes meta-data added at the top of the .md files and will update the appropriate fields of the created/updated post during the import process.

For example:

---
title: Title to use in HTML <head>
description: Meta description to use in HTML <head>
keywords: meta keywords to use in HTML <head>
excerpt: Excerpt associate to the Item in b2evolution...
short-title: Short Title used in sidebar navigation
extra-slugs:
    - synonym-a
    - synonym-b
tags: [Hacker, Hacking]
extra-cats:
    - background
    - in-real-life
    - fun
order: 123
item-type: Post with Custom Fields
---

# Full Title of the page

• title: defines the title to be used in the HTML <title> tag.

  Note: the main ("h1") title of the post is defined by your first # Title in the markdown text.
• tags: defines Tags for the Item. In update mode, if tags: is provided, all existing tags of the Item will be replaced (if tags: is not provided, tags won’t be modified). Non-existent tags specified here will be created as needed.
• extra-cats: allows to specify a list of extra categories. In update mode, this will replace all existing extra categories of the Item. Non-existing categories will display an error and will be ignored. If extra-cats: is not specified, update mode will remove any existing extra categories (because update mode gives priority to moving posts to new location by reusing slug).
• order: defines order per each category of the Item

• item-type: defines Item Type for the Item by name

  Note: the main category is always defined based on the directory structure where the .md file is found.
• PRO extra-slugs: allows to specify a list of extra slugs.
  • In UPDATE mode, slugs will be appended to existing list of slugs.
  • No old slug will be deleted in UPDATE mode.
  • If a slug already matches an existing slug like extra-slug on same Item, nothing special happens.
  • If a slug already matches an existing slug like extra-slug on a DIFFERENT Item, an ERROR will be logged.