jhuntwork
Create a wiki
It is great moment to create wiki to put there documentation like this, either here on GitHub or standalone on merelinux.org
Originally posted by @lufv in https://github.com/jhuntwork/merelinux/issues/362#issuecomment-921624063
--
It would be very helpful to have others contributing to documentation, a wiki of some kind should make this easier.
I really like musl's wiki. It is backed by a git repo where people make pull requests and is just simple Markdown that is then published as static html.
It seems musl's wiki is using tool called makedown. I've also found few other solutions that look somewhat more advanced that makedown:
- https://mycorrhiza.wiki/
- https://github.com/gollum/gollum (screenshots)
- https://github.com/claudioc/jingo
And there are also full blown wikis like those:
- https://github.com/jgm/gitit
- https://js.wiki/ (demo)
Awesome, thanks for the research!
Here's my thoughts on each of the above:
makedown
Pros
- Simple. It seems like it's really just a Makefile and a few scripts that is gluing together some 3rd party tools. Might even be easy to substitute some tools for others as the need arises. The listed tools seem lightweight and easy at first glance.
- Built for Markdown
Cons
- Maybe lack of features? I'm uncertain if this really is negative since it might be too early to tell what additional features beyond a git pull request workflow would be desirable.
mycorrhiza
Pros
- Written in Go
- Possibly some interesting features in linking content, hard to tell yet
Cons
- Requires running a custom service (maybe that's not too bad, it's Go so it's probably not a heavy, or difficult service to manage)
- Has its own markup language. Seems like it's not too bad, not too different from Markdown, and I'm sure there's a good reason for it. It's just... unusual.
gollum
Pros
- Lots of interesting, possibly useful, features, like support for various markup languages
Cons
- Written in Ruby. Mere doesn't have a ruby package right now and I'm not in a hurry to add it. I'm not completely ruling it out, just, meh, not really interested in adding it now. :) I would consider adding it if someone had a strong use case, or it was a community supported package.
jingo
Pros
- Takes inspiration from gollum, seems to try hard to improve on it, so full featured, but aims to be easy to use
Cons
- Node.js. Same thoughts as with Ruby, but even more strongly meh. :) Really want to avoid a node dependency nightmare
- Also requires a running service, and this one seems more involved
gitit
Pros
- Written in Haskell
- Lots of potentially useful features, including Github auth and various markup support through pandoc
- Backend store is a local git repo
Cons
- Requires running a custom service, but again perhaps not too bad if it's self-contained.
js.wiki
Not really going to dive into the pros/cons on this one, I'm sure it has some good features, but my impression is that it's overkill for what I'm looking for and, again, it's Node.js.
And one final one that wasn't mentioned:
hugo
Pros
- Written in Go
- Can render out to static content that can be hosted anywhere
- Mostly just Markdown
Cons
- Theming has been... challenging. In my opinion, most of the available themes are overkill and not oriented enough towards a technical community. I'm sure it's possible to write one that does what we want, but I'm not hugely interested in doing that. If someone else is, that's fine. :)
From the above list, the ones I'm most interested in looking at are makedown and gitit. But obviously, that's my personal opinion, and most of the above list is very subjective. I'm happy to consider other people's views though, especially since I hope to not be the only one creating content.
I have used DokuWiki www.dokuwiki.org/dokuwiki at Obarun wiki.obarun.org for a couple of years, no problems, I can't say I love it or have much of a reference frame. You can mix and blend html code together with its pretty standard md language to edit documents, so if you have groups at html and want to just break out the headers for indexing in md it is pretty straight forward.
You would think that by now there would be easy tools to go from md to html to pdf and back ... as I found out, md --> html is pretty simple, the other way is very unreliable ... I couldn't believe it, and I am talking about really plain jane html documents, like those found at skarnet for s6. (by the way there is someone who has taken the project personally and has produced the entire s6 documentation in .md so one can make man pages if they choose to out of it.).
I should be partial to mychorrhiza due to the name, and it does look very interesting, I've never heard of it before.
Another decision for design, should there or shouldn't be support for man pages and man software?
It is hard to believe yet another polarization between lovers and haters of % man
Truly fungal activity in FOSS
I have used DokuWiki in the past and have similar feelings. It's usable.
As for man pages, I've been a little uncertain about policy on that one. Originally I was leaving them out to try to keep things small. But the more I used the system without them, the more I missed them. Right now the reader, mandoc is an optional install, but the pages themselves I've been shipping with the packages.
Added a "wiki" of sorts here: https://github.com/merelinux/wiki - Anyone is free to make pull requests and upon merging to the main branch, a github action will publish it to https://merelinux.org