It was discussed a couple of times during the past Kamailio development meetings and several days ago the works started to convert the Kamailio Wiki content to markdown format and host the files on Kamailio github.com organisation.
The Dokuwiki engine has served us very well during more than a decade and a half, but open editing had to be disabled many years ago due to bad actors pushing inappropriate content. The contributors had to make a dedicated account on our portal only for Wiki editing. More recently we had add another layer of protection requiring to grant manually edit permissions to newly created wiki accounts because bots started to work around CAPTCHA and other security extensions, posting again inappropriate content.
All these added to operational overhead, but also made it difficult for new people to contribute, specially for small editing to fix typos or add usage examples.
Thanks to Kenneth Stowe, who undertook the first big effort of converting the Dowkuwiki files to markdown format, we are now in the position of moving further with the plans of using github for hosting the content of the wiki and enable easier contributions via pull requests. The history of changes done via Dokuwiki show up now as git commits.
The github repository for the wiki content is available at:
It is still work in progress, therefore we ask for the help of community to speed up the conversion, among the tasks that need to be done:
- convert relative links between wiki pages – the conversion tools used relative paths without file extensions, like:
[Install Kamailio v4.4.x From GIT](/install/4.4.x/git)
They have to be converted to relative path with .md extension in order to be able to browse directly :n the github.com portal — practically the leading / has to be removed and .md added at the end, like:
[Install Kamailio v4.4.x From GIT](install/4.4.x/git.md)
- some section heading markers were not detected/converted, once may notice many equal signs (=) around a section name, it has to be replaced with the appropriate markdown format based on hash signs (#). For example:
======= Install And Maintain Kamailio v4.4.x From GIT =======
Should be converted to:
# Install And Maintain Kamailio v4.4.x From GIT
- some Dokuwiki paragraphs used special formatting based on plugins, for example the notes, warnings, … had special colors. The common markdown format does not specify a syntax to color the text, the propose solution is to use emoji at the start of the paragraph to signal its special purpose. For example, the Dokuwiki content:
<color blue>//IMPORTANT: Content for older releases than 3.2.0 is available at the **Old Wiki Site**://</color>
Has to be transformed to:
:fire:*IMPORTANT: Content for older releases than 3.2.0 is available at the **Old Wiki Site**:*
You are welcome to propose a better syntax for this kind of transformation.
- review config examples and evaluate what improvements can be done (e.g., in terms of formatting and syntax highlighting)
Any of these changes do not require any C programming knowledge, nor much Kamailio config knowledge. Can be your first contribution to the project and it will be very appreciated. It can also help you learn more about Kamailio, because you may discover documentation that you were not aware of.
A very important decision is how to present the wiki markdown content on kamailio.org website. Besides being able to see it on github repository, we want to process the markdown pages somehow and make them available in html format on kamailio.org website for easier navigation and better indexing (e.g., with tables of content for large pages). If you are aware of a suitable cli or web app that can convert markdown to html and generate table of content, let us know.
Any questions and suggestions should be addressed to sr-users@lists.kamailio.org mailing list. Looking forward to your contributions on this community effort!
Thanks for flying Kamailio!