A Python tool that converts all HTML pages from DokuWiki-based sites to Markdown format.
Key Features:
- Authentication using browser session cookies
- Preserves relative links between pages
- Downloads all media files and updates paths
- Pluggable converter architecture (MarkItDown, Pandoc, html2text, HTML)
- HTML mode with internal link rewriting to local relative paths
- CSS download for offline-ready HTML output (auto-downloads server CSS, supports custom CSS injection)
- Pages and media are downloaded in parallel for improved speed
- Number of workers configurable in
config.json
- Generates
output/report.txtafter conversion - Includes success/failure statistics, file lists, and error details
Supported Converters:
| Converter | Pros | Cons |
|---|---|---|
| markitdown | Microsoft-backed, various formats | Not DokuWiki-specific |
| pandoc | Document conversion standard, high quality | Requires system installation |
| html2text | Lightweight and fast | Weak on complex structures |
| html | Preserves original HTML, rewrites links to local paths | No Markdown conversion |
Configuration (config.json):
{
"base_url": "https://your-dokuwiki-site.org",
"namespaces": ["docs:api", "guides"],
"cookies": {
"DokuWiki": "YOUR_COOKIE_HERE"
},
"converter": "markitdown",
"output_dir": "output",
"rate_limit": 0.3,
"parallel": {
"max_workers": 5
}
}The converter field accepts either a string or an object with per-converter options:
// String (backward compatible)
"converter": "markitdown"
// Object with options (html converter example)
"converter": {
"name": "html",
"download_css": true,
"css": "custom.css"
}| Key | Required | Default | Description |
|---|---|---|---|
base_url |
Yes | - | DokuWiki site URL (include subdirectory path if applicable, e.g. https://example.org/wiki) |
namespaces |
No | [] |
Array of namespace/page paths. When specified, only pages under these paths are downloaded/converted. If omitted or empty, all pages are processed. |
cookies |
No | {} |
Authentication cookies |
converter |
No | "markitdown" |
Converter selection — string or object. String: converter name. Object: name + per-converter options. |
converter.name |
No | "markitdown" |
Converter name (markitdown, pandoc, html2text, html) |
converter.download_css |
No | true |
(html only) Auto-download server CSS files for offline viewing |
converter.css |
No | "" |
(html only) Path to custom CSS file to include in output |
output_dir |
No | "output" |
Output directory path |
rate_limit |
No | 0.2 |
Delay between requests in seconds |
parallel.max_workers |
No | 5 |
Number of parallel download workers (falls back to sequential if less than 2) |
# 1. Install dependencies
pip install -r requirements.txt
# 2. Edit config.json
# - Set base_url
# - Choose converter (markitdown, pandoc, html2text, html)
# - Copy cookies from browser DevTools → Application → Cookies
# 3. Run
python doku2md.py
# or
python -m doku2md
# 4. Check results
ls output/pages/
ls output/media/
ls output/css/ # HTML mode only
# 5. If conversion quality is poor, try a different converter
# Change "converter": "pandoc" in config.json and re-run- Log in to your DokuWiki site in your browser
- Open DevTools (F12) → Application → Cookies → select the domain
- Copy the Value of the
DokuWikicookie - Paste it into the
cookiessection of config.json
markitdown>=0.1.0
requests>=2.28.0
beautifulsoup4>=4.12.0
tqdm>=4.65.0
html2text>=2024.2.26
Optional Dependencies:
- Pandoc: Requires separate system installation (
apt install pandocorbrew install pandoc)
MIT