137 lines
3.9 KiB

# dokuwiki-to-hugo
A DokuWiki to Hugo file exporter to quickly migrate your existing PHP wiki to Hugo
**How do I run this thing?**
##### Running it from command line
Just use the main python class. It uses `argparse`:
`python src/ --dir='some_dokuwiki_root_dir'`
Command line options:
- `--dir`, the directory of your DokuWiki pages collection.
- `--frontmatter_tags=true`, whether to generate tags in the converted Hugo markdown. By default, the tool generates
tags based on the path to the document.
##### Running unittests
`python` in root folder. `-m unittest` does not work as imports mess up `src`/`test` subfolder structures.
##### Including it into your python project:
Main wiring in `DokuWikiToHugo` - see the tests for an elaborate example.
This generates files in a new folder called 'output' with the same directory structure.
## TOML File headers
Every converted file contains a TOML header with:
* datestamp - looking at the file modified date (transfer from your FTP using 'keep timestamps' option)
* draft automatically set to false
* tags: every subfolder is a tag, including the name of the file
* title: name of the file
See `` for an example.
## Following Dokuwiki syntax converted:
### general
Things that needed some conversion:
* code, file, inlinecode with single quotes
* italic, strikethrough
* headings with equal sign
* linebreaks (double backslash) are at this moment replaced with HTML BRs.
* ordered lists using dash to markdown
* emoji following this cheat sheet: - don't forget to enable emoji in your hugo config.
Things that are **the same** anyway:
* horizontal rule (4 slashes VS 3 or more)
* bold stuff using double asteriks
* unordered lists as asteriks
* sub/sup
### embedding HTML
Since Hugo still supports html tags, we don't need to do anything but to remove the `<html/>` tags.
See also the `MarkdownInlineHtml` class in simplestyle module.
### links
Simple internal links are converted to relrefs like `[[mylink]]`. Local links with double colon are replaced by forward slash.
`[[sub:link]]` would become a link to the sub/link article.
If it's a HTTP(S) link, it stays that way.
#### interwiki
You'll have to come up with your own shortcodes for those.
See wp.html in the layouts directory. You could customize interwiki links from dokuwiki: `[[custom>somelink]]` would refer to some custom wiki.
Simply add custom.html and link to the website of your choice. Use Hugo's `{{ index .Params 0 }}` to get the link content.
### Images
Images are supported using the double `{{` syntax:
1. simple image: ``{{someimg.jpg}}``
2. positioning; left-right using space: ``{{ somerightaligned.jpg}}``
3. dimensions: width only ``{{someimg.jpg?400}}``
4. dimensions: width and height ``{{someimg.jpg?400x300}}``
Of course combinations are also possible.
### TODO's
There's a dokuwiki plugin which enables things like:
<todo>a todo list</todo>
<todo #>done</todo>
<todo #>also checked off</todo>
Hugo supports this using this MD syntax:
- [ ] a todo list
- [x] done
- [x] also checked off
I like lists. So this is naturally supported.
### I want to create my own syntax conversion!
No problem, the project was made with extensibility in mind.
Simply drop a python script in the markdown submodule folder location and annotate it with the class decorator `@MarkdownConverter.Register`.
That way it's auto-loaded and wired in the main conversion.
### styling
* Tables, should complex ones be supported or can I do a manual convert?
* no formatting (nowiki, %%) - should this just be a pre?
### Not supported and probably will never be
* embedding php - kill it with fire?
* macro's - kill it with fire?
* what to do with footnotes?