README.md
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!
