2017-01-12 16:23:00 +01:00
|
|
|
# dokuwiki-to-hugo
|
2017-01-14 11:09:42 +01:00
|
|
|
|
2017-01-12 16:23:00 +01:00
|
|
|
A DokuWiki to Hugo file exporter to quickly migrate your existing PHP wiki to Hugo
|
2017-01-14 11:09:42 +01:00
|
|
|
|
|
|
|
See https://www.dokuwiki.org/wiki:syntax
|
|
|
|
|
2017-01-15 15:52:25 +01:00
|
|
|
**How do I run this thing?**
|
|
|
|
|
|
|
|
Main wiring in `DokuWikiToHugo` - see the tests for an elaborate example.
|
|
|
|
|
|
|
|
```python
|
|
|
|
DokuWikiToHugo().doku_to_hugo('some_dokuwiki_root_dir')
|
|
|
|
```
|
|
|
|
|
|
|
|
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 `test_hugo_file_config.py` for an example.
|
|
|
|
|
2017-01-14 20:14:18 +01:00
|
|
|
## Following Dokuwiki syntax converted:
|
|
|
|
|
|
|
|
### general
|
|
|
|
|
2017-01-15 17:33:15 +01:00
|
|
|
Things that needed some conversion:
|
|
|
|
|
2017-01-14 20:14:18 +01:00
|
|
|
* code, file, inlinecode with single quotes
|
2017-01-15 17:33:15 +01:00
|
|
|
* italic, strikethrough
|
2017-01-14 20:14:18 +01:00
|
|
|
* headings with equal sign
|
|
|
|
* linebreaks (double backslash) are at this moment replaced with HTML BRs.
|
2017-01-15 17:33:15 +01:00
|
|
|
* ordered lists using dash to markdown
|
|
|
|
* emoji following this cheat sheet: http://www.webpagefx.com/tools/emoji-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
|
2017-01-14 20:14:18 +01:00
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
2017-01-15 20:40:23 +01:00
|
|
|
### TODO's
|
|
|
|
|
|
|
|
There's a dokuwiki plugin which enables things like:
|
|
|
|
|
|
|
|
```html
|
|
|
|
<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.
|
|
|
|
|
2017-01-15 17:33:15 +01:00
|
|
|
### 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.
|
|
|
|
|
2017-01-14 11:09:42 +01:00
|
|
|
## TODO
|
|
|
|
|
2017-01-14 20:56:16 +01:00
|
|
|
### styling
|
|
|
|
|
2017-01-14 11:09:42 +01:00
|
|
|
* Figure out image links ala http://php.net|{{wiki:dokuwiki-128.png}}
|
|
|
|
* Tables, should complex ones be supported or can I do a manual convert?
|
2017-01-14 20:56:16 +01:00
|
|
|
* no formatting (nowiki, %%) - should this just be a pre?
|
|
|
|
|
2017-01-15 17:33:15 +01:00
|
|
|
### Not supported and probably will never be
|
2017-01-14 11:09:42 +01:00
|
|
|
|
|
|
|
* embedding php - kill it with fire?
|
|
|
|
* macro's - kill it with fire?
|
|
|
|
* what to do with footnotes?
|