Bringing docs/wiki to a new tech stack

Talk about Documentation
1

I discussed some options with @aparcar today about the future of the openwrt wiki.

The technological status quo of the mediawiki is quite dated. We are looking for a way to use a better future proof technology for this.

Historically, the mediawiki has the function of 3 tools:

  1. welcome, releases, contact, links to important pages
  2. toh, devices, instructions
  3. user created docs, FAQ, recurring installation and development guidelines

@aparcar already drafted a new solution for the first part: https://aparcar.codeberg.page/openwrt-org/
(source is here: https://codeberg.org/aparcar/openwrt-org/ )
This looks good, is based on hugo (SSG) and is editable by the openwrt team, while everyone can make suggestions through a git-based workflow.

No. 2/3 should be user editable, and I guess that we do not want to rely fully on GitHub for editing.

For 2. the LineageOS approach mentioned in https://lists.openwrt.org/pipermail/openwrt-devel/2025-February/043774.html is quite good and has been followed here: https://aparcar.org/openwrt-devices/devices/tp-link_archer_c7_v5/ (source: https://github.com/aparcar/openwrt-devices ) - but does not easily enable editing by users.

For 3. we need a proper wiki for sure anyway.

Users

As the forum software Discourse does not provide an OIDC/OAuth2 endpoint (but rather can consume one), the login for the wiki must be newly created when migrating as we can’t really migrate the existing users either.

The decision on a way forward should be made in consultation of the community and wiki users. That’s why I am posting here.

Wiki-Software

Possible alternatives are https://docmost.com/ , https://www.notion.com/ , Wiki.js (https://js.wiki/) and others (feel free to suggest things).

I currently think that wiki.js would be a good solution, as it has a solid Git-based backend and therefore can be eventually used to store editable markdown files, which are then consumed by other tools (e.g. the openwrt-devices page).

I wonder though how large edit volumes are handled and if it suits for the size of OpenWrt project.

Current Tweaks in DokuWiki

Unfortunately, there are many tweaks in the current openwrt Wiki:

  1. Indexes are automatically created with scripts (migration or replacement needed)
  2. placeholders for warnings and notes are inserted into other wiki pages (not possible in wikijs)
  3. various tables can be created from ToH and are embedded into the articles (maybe possible customization https://github.com/requarks/wiki/discussions/6506 )
  4. scripts automatically update all occurances of e.g. latest release links
  5. …

Do you see other things/requirements to a new solution which must be respected?

What do you think of splitting up representation from the dokuwiki web page?

2

I'm pretty much fine with any of the choice, but one thing that needs significant work is the search functionality.

The current search is truly terrible, you get 98% ToH docs when you're searching for, say, config file syntax, making it pretty worthless. If we had a better search engine, that would make life so much easier for everyone.

3

I’d like to put an emphasis on the explorative nature of this. Nothing is decided and it’s specifically important to incorporate the opinions of both project members and active wiki authors. I found it easier to discuss when showing alternatives, so I created a bit of a demo. However this is by no means the final nor approved version.

4

First of all thanks to @aparcar and @fmaurer for taking the initiative.

I, too, would like to see a next level of the documentation.

I can't stress enough that we need a git-based workflow.

What I'd like to see in the next gen documentation, besides

  • the technical and hardware low level specs;
  • the user facing install instructions and device specifics;
  • software or package documentation (how to use; how to configure; option references)
  • the current recipes (dump ap; various ipv6 setups; ...)

What I'd like to see is in addition are "branched" recipes or setup.
Most recipes are to narrow in my opinion and lag a good general explanation so users can easily adapt. By "branched" I mean that there could be multiple documents covering the same thing slightly different.

We should also spend some time reading documents back and forth, till we find a good "ordering" of documents, like with the current building openwrt section.
I think it's highly confusion for new once not only to decide if the user needs to build (compile) the source, or if the image builder just suites enough...

What I'd like to see no longer:

  • Hacky one-shot uci scripts, because these are blindly run by new user
  • If uci-scripts are used, then these sections should be shown as config stanza sections, too

Just my two cents during the first coffee.
Besides that: GO GO GO!! :partying_face:

5

I fully agree with that :+1:

6

I absolutely agree that dokuwiki is showing its age. Search is a big one, and the fact that it doesn't use Markdown is another.

But I feel the need to explore this statement:

What are the important attributes of a git-based workflow? What benefits would it bring? What would it protect against?

My take: I am an admin on a git-based website, and it's a pain in the patootie. Because each site update is a commit, people are reluctant to make necessary tweaks in the name of "keeping the commit history clean". (Use case: I recently posted a new page on the OpenWrt site. I needed to make 50 edits from my initial draft on 1 July to now. That's a lot of edits, but the page is really the way I want it now.)

Futhermore, a git-based site makes it hard to have a wide variety of people adding or editing information. Instead it concentrates the responsibility for updates on the shoulders of a small number of people - they may be experts overall, but they surely don't know all the details of every topic.

One of the strengths of the OpenWrt wiki is exactly the same strength of Wikipedia: people who happen to know something, and are willing to make / update an entry cause the totality of the wiki to improve.

Note: I'm not saying that the wiki doesn't need a roll-back mechanism to protect against mistakes or vandalism, just that we don't need the full power and glory of git to get there. Thanks for listening.

7

A git based workflow allows (IMHO) easier comparison of versions. Most "wiki" based solutions are limited are even no use at all once the text base is huge or if formatting is not handled well.

I see and understand your points /against/ git, but from my experience, once a (large) text is "settled" most edits are small. And a huge change is easier to track with git, like with long lived feature branches a huge edit can be done in separate and edits on the base can still be tracked.
(I use line based and word based diffs to read text changes and if users for instance try to put one statement/thought/sentence into a single line then it can be quiet nice and clean.)

No I don't thing so. 1) See gitlab and github WYSIWYG edtior. 2) Markdown should or could be considered a no-brainer 3) If someone is not "able" to use markdown or a git-based (web-editor) workflow... I'm not quiet sure if that person is "capable" of providing /good/ technical explanation and such to other users. I don't want to sound elitism but ... yeah don't know... but maybe I'm biased... But with the gitlab/github editors even non-technical users should be capable of fixing small and spelling mistakes and they could even comment on individual lines, or do "feature request" or submit changes as a merge request.... so, and that is maybe the most important point: changes can easily reviewed upfront.
My main point with git is that I think its easier and better in the long run, and it should be easier then the user account management of a classical wiki...

Thanks for your input and concerns!

PS: I'm still with my first coffee... just sayin' ^^

8

In lieu of a new stack, dokuwiki just released 2026-07-14 "Mort", with what I consider a significant change:

https://www.dokuwiki.org/markdown

tldr: This release allows you to configure markdown parsing to use their traditional markdown, github-like markdown, or both simultaneously.

Don't know about you all, but I know that I'm forever using backtick in my dokuwiki content and then having to go back and replace it with ''double quotes'' and <code> blocks, so this alone looks like a big win for me. I have yet to use it on my home wiki, but as soon as I upgrade here, I'll play with it and report back.

9

Not going to lie I absolute hate the '' '' syntax and also having to do something like ''something %%'1'%%'' to escape single quotes as well. Markdown formatting would be welcome!

10

When it comes to search functionality, I didn’t see https://pagefind.app mentioned in this discussion yet. I recently implemented a small multilingual web site with Hugo and a self-built theme. Pagefind is a Javascript based search that works on a static web server. The browser would fetch and execute some Javascript and WebAssembly code that would then fetch the required inverted index files as you start typing a search term. There are some options for tweaking the index generation. For the web site I worked on, the defaults (such as prioritizing words occurring in section headings) worked fine.

Some tweaking of the output is necessary, such as the following to be dark mode friendly (extracted from our .gitlab-ci.yml):

      sed -i -e
      "/^\[data-pf-theme=\"dark\"\] {/,/}/ {
      s/\[data-pf-theme=\"dark\"\] {/@media (prefers-color-scheme: dark) { :root {/;
      s/}/}}/;
      };
      s/ color-scheme: \\(light\\|dark\\);//;
      /.*\[data-pf-theme=\"dark\"\].*{/,/}/ { d; };"
      pagefind/pagefind-component-ui.css

We also tweaked the output so that the static parts (Javascript and CSS) would be relocated to a content delivery network, and added some Javascript to defer loading any of that code until the user clicks on the search button or types the keyboard shortcut Ctrl-K.

There is an intention to package Pagefind in Debian, but it is taking time due some technical challenges. In the setup that I worked on, we’d extract the executable from a Docker image.