Experiences with Markdown to DokuWiki Converters?

Having spent some time with the "classic" OpenWRT Wiki and the lack of a WYSIWYG editor (no, the "Preview" button doesn't count), my future contributions are going to be very limited if I can't use a 21st-century tool to do the authoring. Even early 2000s would be OK :wink:

As far as I can tell, it's running DokuWiki.

I don't mind markdown and there are some good tools that have real-time WYSIWYG editing. However, converting that reliably to and from DokuWiki is an open question. Before I head down that path, has anyone had good or bad luck with Mac- or `Nix-based tooling?

1 Like


It is.

Well, you've lost a Wiki contributor at this point.

The amount of time required to make even a simple edit is far too much, between the obtuse syntax, that you can't easily link to other wiki pages (come on, the popup doesn't list the pages I just visited, doesn't auto-complete, and won't link to anchors within a page), and no live preview, it's not worth it.

https://pandoc.org/try/ will convert to DokuWiki format, but not from.

I'm pretty sure there are some GUI editing plugins, perhaps one can be installed?

EDIT: example https://www.dokuwiki.org/plugin:ckgedit

not sure if it is sufficiently full featured for @jeff's needs but it's probably a good idea to have something like this.

1 Like

I'm sorry to hear this. I'm certainly not in love with the Dokuwiki syntax, but it is usable. In addition, we collected thousands of articles in the OpenWrt wiki over the last decade. It would be a massive effort to change to a new Wiki.

I have read about a couple Markdown plugins for Dokuwiki. They sound attractive, but each suffers from different problems: lack of updates, peculiar interface into Dokuwiki, imperfect Markdown rendering...

I'm curious: what areas of expertise do you have that you would consider adding to the Wiki? Perhaps there's a way to capture your knowledge without too much exposure to Dokuwiki... Thanks.


Thanks for the consideration @richb-hanover. It's not just for myself, but also the other potential contributors out there that are likely frustrated as well.

I've been using OpenWRT since the original WRT54g and White Russian in multi-AP configurations, hard-wired in the early days, moving to WDS, and now 802.11s. I take copious notes of configuration and would like to be able to save others the time of finding out all the things that don't work, especially when it is so difficult to find documentation, even around UCI parameters. Even when an appropriate page is found, it is often incomplete, outdated, or flat-out wrong. As a specific example, I could not find any documentation on the parameters around switch configuration (yes, I added the section that is there now).

So as to the "what" it would be trying to organize and clean up the UCI documentation so that, for example, a user could find a page on /etc/config/network and have a clear, current, complete, and correct definition of what the various sections are, what the options available are and the range of valid parameters, and what each option actually does. Personally, moving the "examples" and "how to" sections out of the "man page" and into appropriate locations would make configuration a lot easier. I understand the "customers" that find LuCI sufficient for their needs, but there are many things that can't be configured in LuCI, especially for sophisticated users. Those are the users that drive technical innovation within OpenWRT.

Past that, documenting in a series of "How to" articles:

  • Setting up "dead-end" IoT networks
  • Supplying limited services and limited outside connectivity to IoT devices
  • Configuring 802.11s
  • Configuring bridged VLANs over gretap (over 802.11s)

As a product manager for enterprise software by trade, I understand the value of good documentation. That value is not only for those using the software, but also those considering their options. While OpenWRT is not a commercial product, there certainly are commercial entities that consider it for and may choose to use it in their embedded systems. Getting "return" from these professional endeavors can enhance OpenWRT, but only if they choose it over the alternatives.

Alternatives like FreeRTOS (now unencumbered by GPL with its acquisition by Amazon) running on ARM and the various derivatives are challenging the position of embedded Linux, especially with SoCs now providing TLS-enabled, IPv4/6, 802.11 stacks, and BLE stacks. Yes, these companies do give back, even when the license terms don't require them to do so. The powerful netgraph infrastructure in FreeBSD is a specific example I've been utilizing for years -- contributed by Whistle Communications even though there was no requirement in the BSD license to do so.

As a professional, looking at the OpenWRT documentation, which is only the Wiki, would I have confidence that my development team could work with it? In the state it is in, no. When I look at, for example, http://www.ti.com/product/cc3220 and the associated RTOS documentation, as a professional, I have a lot more confidence that my team could execute on scope, schedule, and cost.

Let's not lose the potential of professional contributions before the window of opportunity closes. Yes, there is a lot of good work among decade of contributions there. Please make it easier for those willing to try to make it both more usable and more professional to help the community in general.

Edit: To be clear, WYSIWYG editing would be sufficient. I switch between various flavors of Markdown and Confluence multiple times a day at work. It's seeing that I've got the wrong syntax as I type that makes it less problematic. I can quickly try something else and, for example, figure out how to type either <done> or <done> without having it converted to an HTML tag. It's also dealing with tables, that impossible for most humans to comprehend in any markup, and core to so much of the OpenWRT documentation, that is made so much easier with a "live" preview.

1 Like

Seems like there are several...


An example from dokuwiki for a Markdown to DokuWiki plugin...


@jeff What a thoughtful note and plan. I think you've identified two topics:

  1. You find Dokuwiki syntax off-putting. We should investigate those Markdown plugins to see if they could work for the kinds of edits you envision.

  2. You care intensely about the quality of the documentation. As a member of a small team that's focused on maintaining and improving the wiki structure, we agree. Most recently, we're digging out from the merger of the OpenWrt wiki with the pages of the LEDE wiki. Longer-term, we're working to set up the wiki so that contributors who follow the pattern of well-constructed articles will automatically make the wiki better.

If you have the energy, I would ask you to join with us. Thanks.

ckgedit is no option, since it breaks the data plugin. Completely.

Example: You enter a dataentry page in WYSIWYG mode, decide to go to Dokuwiki editor mode, et voila, all you see is "false". Nothing else, just "false", blank screen where content should be.
Mind that you havn't edited a thing, not even a missing . or a space.

Sigh... :slight_smile:

That editor can be disabled in defined namespaces though, so you can just have it disabled for articles in the ToH/datatable/ToP.



A comma separated list of files and namespace where the Dokuwiki editor is automatically loaded instead of the CKEditor. The code looks only for partial matches. So if you have “jack”, it will find “blackjack” and “jack_pine”.

Although if this thing breaks even if it reads an article where we place a datatable string (like say to show some package data from the ToH in an article about that package, or device data from the ToH in a device article), this would restrict the use of the datatables to whitelisted namespaces. Still 100% worth it imho.

I noticed already that ckgedit can be excluded from namespaces, and ToH/datatable/ToP would cover most of them, but the remaining pages are at high risk. We could of course exclude more namespaces, but then the number of pages where ckgedit is available would become so low that we would need to ask ourselves why it is there in the first place.

Question to all: What is the one thing that you like the most on ckgedit?

  • general WYSIWYG?
  • especially table editing?
  • something else?

At high risk of what?

How many wiki editors have ever used the data plugin in the wiki apart from you and me (to a lesser extent) for the ToH and ToP?

Even in the old wiki I don't see anyone else that used it. I think it's fine if it becomes unavailable outside of the right namespaces.

Also, it seems you can open the normal docuwiki editor even if the new editor is active:


Clicking on a dokuwiki section while ckgedit is active will open that section for editing in the native dokuwiki editor. This feature is on by default and can be set to off with this option.

Question to all: What is the one thing that you like the most on ckgedit?

WYSIWG editor mostly.

Would be cool to have a better way to generate internal links too, as I think the current panels aren't that easy to understand, if the ckgedit internal links work like in this video https://www.youtube.com/watch?v=Jc_wzayCLFY I think it would be an improvement.