1# mdimport plugin for DokuWiki 2 3**Import Markdown files directly into the DokuWiki editor.** 4 5This plugin adds a toolbar button to the edit page, allowing you to select a Markdown (`.md`) file from your computer. The file's content is automatically converted to DokuWiki syntax and inserted at the current cursor position. 6 7All documentation for this plugin is available at: 8**[https://www.dokuwiki.org/plugin:mdimport](https://www.dokuwiki.org/plugin:mdimport)** 9 10--- 11 12## Important – Folder Name 13 14If you install this plugin manually, make sure it is placed in: 15 16 lib/plugins/mdimport/ 17 18If the folder is named differently, the plugin will **not** work! 19 20For general information on installing extensions in DokuWiki, see: 21[https://www.dokuwiki.org/extensions](https://www.dokuwiki.org/extensions) 22 23--- 24 25## Features 26 27- **One‑click import** – Select a Markdown file from your computer, and its content is converted and inserted at the cursor position. 28- **Full conversion** – Supports common Markdown elements: 29 - Headers (`#` → `======`) 30 - Bold (`**text**`), italic (`*text*`), inline code (`` `code` ``) 31 - Links (`[text](url)` → `[[url|text]]`) and images (`` → `{{url|alt}}`) 32 - Unordered and ordered lists (with nesting) 33 - Tables (with column alignment) 34 - Code blocks (with language hint) 35 - Blockquotes and horizontal rules 36 - YAML front matter (automatically stripped) 37- **Live preview** – Conversion happens in the background via AJAX; the resulting DokuWiki syntax is inserted immediately. 38- **Lightweight** – No external dependencies; pure PHP and JavaScript. 39 40--- 41 42## Requirements 43 44- **DokuWiki** – any recent version (tested with **2025‑05‑14 “Librarian”** and later) 45- **PHP** – 7.4 or higher (uses typed properties and `str_starts_with`) 46 47--- 48 49## Installation 50 511. **Download** the plugin from [GitHub](https://github.com/yourusername/dokuwiki-plugin-mdimport) or the [DokuWiki plugin repository](https://www.dokuwiki.org/plugin:mdimport). 522. **Extract** the contents into `lib/plugins/mdimport/` of your DokuWiki installation. 533. **Enable** the plugin via the DokuWiki extension manager (Admin → Extension Manager) or by setting `plugin»mdimport»enabled = 1` in the configuration. 54 55The plugin should appear immediately on the edit page toolbar. 56 57--- 58 59## Usage 60 611. Open any page in edit mode. 622. Click the **“Import Markdown file”** button (�� icon) in the toolbar. 633. A file picker dialog opens – select a `.md` or `.txt` file. 644. The content is converted and inserted at the current cursor position. 65 66The conversion uses an internal PHP class (`MarkdownToDokuWikiConverter`) and returns pure DokuWiki syntax, so you can further edit the imported text as usual. 67 68--- 69 70## Supported Markdown Syntax 71 72| Markdown | DokuWiki | Notes | 73|----------|----------|-------| 74| `# Heading 1` | `====== Heading 1 ======` | Level 1–6 supported | 75| `**bold**` or `__bold__` | `**bold**` | Same in both | 76| `*italic*` or `_italic_` | `//italic//` | | 77| `` `code` `` | `''code''` | | 78| `[link](url)` | `[[url|link]]` | | 79| `` | `{{image.jpg|alt}}` | | 80| `- item` or `* item` | `* item` (unordered) | Nested lists use two‑space indentation | 81| `1. item` | `- item` (ordered) | Ordered lists become DokuWiki unordered lists with a dash; numbering is not preserved | 82| `> quote` | `>> quote` | | 83| `---` | `----` | Horizontal rule | 84| `` ``` `` | `<code>` and `</code>` | Language hint preserved (e.g., ` ```php `) | 85| `\| Header \|` | `^ Header ^` | Table rows; alignment is detected from the separator line | 86 87> **Note:** DokuWiki’s syntax differs from Markdown in several places; the plugin aims for a sensible conversion, but always check the result before saving. 88 89--- 90 91## Conversion Details 92 93- **YAML front matter** – If the file starts with a block delimited by `---` … `---` (or `...`), it is removed entirely. 94- **Code blocks** – Opening and closing triple backticks are replaced with `<code>` and `</code>` tags. An optional language hint becomes a class (`<code php>`). 95- **Tables** – The plugin detects the separator line (e.g., `|:---:|---:|`) and uses it to align columns (`^ left ^`, `^ center :^`, `^ right :^`). 96- **Inline formatting** – Bold, italic, inline code, links, and images are converted as shown above. 97- **Paragraphs** – Multiple lines of text are joined with a single space and separated by blank lines. 98 99--- 100 101## License 102 103**Copyright (C) 2026 sioc-de-narf <sioc.de.narf@gmail.com>** 104 105This program is free software: you can redistribute it and/or modify it under the terms of the **GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.** 106 107This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html) for more details. 108 109You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>. 110 111The full license text is available in the `LICENSE` file included with this plugin. 112 113--- 114 115## Author 116 117- **Name:** sioc-de-narf 118- **Email:** sioc.de.narf@proton.me 119- **Website:** [DokuWiki plugin page](https://www.dokuwiki.org/plugin:mdimport) 120 121--- 122 123## Contributing 124 125Found a bug or want to improve the conversion? Feel free to open an issue or submit a pull request on [GitHub](https://github.com/yourusername/dokuwiki-plugin-mdimport). Contributions are welcome!
