For people who are too lazy to search for Ikiwiki:
> Ikiwiki is a wiki compiler. It converts wiki pages into HTML pages suitable for publishing on a website. Ikiwiki stores pages and history in a revision control system such as Subversion or Git. There are many other features, including support for blogging and podcasting, as well as a large array of plugins.
I keep my data in my local network using git (running git-daemon) and -- if I feel I must store it on "someone else's computer" -- I archive it, encrypt, and push it somewhere or I carry it on an air-gappable device.
As someone who has been using a similar strategy for personal notes (namely: notes as plain markdown files in a folder), I agree with some of the strengths mentioned, but also have several issues.
On the pro side, plain text will always be future-proof and basically king of platform independence. Coupling this to Git(Hub) gives you a backup of sorts, access when you are not on your main device, and cross-device syncing.
In my experience, however, several of these are overrated or unused (at least for my own use cases, but I suspect others', too). There are also many missing features. A random list: I don't really need markdown rendering, find the edit workflow of GitHub to be painful for one-liner changes, miss auto-save, find the search feature slow compared to local searches in editors, and if we're talking about a real wiki: I _really_ miss being able to paste screenshots from clipboard as an unnamed / temporary file.
So then, the question is, why bother with GitHub, and not just do this locally with VsCode / Vim / Emacs / editor of choice? And I would basically agree, and the Git/GitHub part can be added as a secondary feature. However, the article seems to be touting this part well above the rest, and my experience is quite the opposite - you rarely end up using those, or _want to_ use those.
What I still miss is auto-generation of a few features. For example, subdirectory indices, in-browser search (can be generated statically and into JS) etc. Then I think it's perfect.
Hi rich_sasha, i am working on a tool that does all that. Hoping to have an alpha ready soon, drop me a line on muji [at] tmpfs.org if you want to give it a try, cheers!
It's written in Haskell, which will thrill some people and annoy some people and make most people shrug.
We used gitit for more than a year, but realized that it just wasn't enough fun to use. Transitioning to Dokuwiki was fast, and it turns out to hold our interest pretty well.
Isn’t the difference really when the static site generator program runs?
You can either run it yourself or in a post-commit/push hook (or a CI action, etc). But aside from that, what do you see as the difference? Automatically adding in the navigation links?
Sure it’s a Git-based wiki. It’s a flat-file content system with full linking and all; it’s not using any special GitHub functionality at all. You can browse this wiki in a text editor (some will let you easily jump between files, e.g. `gf` in Vim, and some won’t), or see it rendered to HTML on any mainstream Git hosting service.
This was my thought as well. What do people disagree about re the definition of 'git-based' wiki?
Do the purists who object to this (in a "Linus Torvalds' definition of git kind of way") fundamentally believe that there should be no central "origin" of any kind in a repo?
Sure, the main attraction in a DVCS is that everyone has a complete copy of the code and can pull branches or integrate changes from anyone else into their work, but eventually these changes have to 'land' somewhere and for most things, that's GitHub/GitLab/whatever other hosting service with git support.
^ This is - for practical purposes - my definition of origin.
Meh, it's usable w/out github but you'll be reading raw markdown files (unless you get your own markdown renderer which isn't that big of a deal). But yeah, it's either an incomplete git-based wiki or a complete github based wiki.
It always goes this way. Some people really want to edit their wiki markup in a plain text editor, others want that superior UI/UX that a system like Dokuwiki offers.
So if you have to optimize for an entire team you end up moving away from plain-text editing.
No one has been able to solve effectively for both use cases.
When Confluence dropped support for plain-text markup editing there was a huge storm about it. Some people are still angry at Atlassian.
> By default, GHC's runtime will repeatedly attempt to collect garbage when an executable like Gitit is idle. This means that gitit will, after the first page request, never use 0% CPU time and sleep, but will use ~1%. This can be bad for battery life, among other things.
As other people noticed, this isn't really a wiki, but attempt to emulate it on github. gitit is a proper git based markdown wiki that we have been using for ~ 8 years. Everything works quite well, except for the fact it is in Haskell. Otherwise the main advantages obviously are the availability of pure wiki interface and possibility of locally editing a file in your own editor and pushing it. Also it is nice to be able to add a bunch of images without having to click many buttons through a simple git add; git commit; git push
> Everything works quite well, except for the fact it is in Haskell.
I don't understand how being written in Haskell can, itself, work well or poorly or not work from the point of view of a user.
Did you mean "despite being written in Haskell", or are there usability concerns that are caused by it being written in Haskell? (... or is there some other interpretation I'm not seeing?)
I wanted to implement a feature, like seing the most recent changes time, or fix a bug https://github.com/jgm/gitit/pull/388 and to implement those I had to learn haskell. That wasn't easy... If the software were written in python/ruby/c/c++/php whatever it'd take me an order of magnitude less effort and time to fix/contribute.
+1 for Gollum. It's lightweight, runs well in Docker, plays nice with other mechanisms for editing the files, and generates everything based on Markdown.
You can use any standard Markdown editor to manage the contents of your wiki, not just their web interface. Is great if the wiki is your source of documentation for your homelab, and need to reference it in the event of your homelab going down completely, with the raw material being just Markdown.
Post-commit hooks can be used to automatically push changes to another location (e.g. a self-hosted Gitea instance running on another host, or Gitlab, or anything else you fancy like just a file store on another host)
EDIT: to note, my primary mechanism for editing my Gollum wiki is their web interface, but having the means to use any other method too is also grand.
I also used Gollum for a while and it's great. You can just
directly create and edit text files and do a commit, or use the
web UI or whatever you feel like.
And it's one of very few systems that support org-mode files in
addition to Markdown, although keep in mind the way Gollum links
files is not quite compatible with org-mode's standard syntax.
Nowadays I just use those org files directly though, as it's
just for my personal use.
Can you access that publicly/via the web browser or always only via spacemacs? I use org-mode and have been thinking it would be nice to set something up to generate HTML and display it on some private website but haven't yet looked to see if there are existing projects that do that.
Github at least displays .org files rendered as they would be in markdown online, so it basically works just like this example from the OP. There are some quirks, but I don't have any specific examples. The basics work just fine.
To me, a git-based wiki is specifically a git repository that contains your wiki data / textfiles. Ideally it would be pure, the web or server code would be kept separate, possibly called/deployed on a git push hook.
It would make far more sense to write and commit and push only plain content, no cluttering the repository with generated markup every time.
This post is a great idea of leveraging github's own repo viewer & markdown handling. Plus they can always add their own web viewer/interface later if needed.
I have a git-based wiki, and I've been slowly migrating it to Trilium [0]. There's a certain appeal to having your knowledge base purely contained within a git repo but ultimately having a rich dedicated editor is less of a hassle to me. Setting up the self-hosted syncing is pretty easy as well.
I've been working this way for a while, but with minimal code niceness:
1. There is an HTML file that just renders with markdown based on the hash. I know hash isn't ideal, but it was easy, and it's all static.
2. Edit buttons on rendered pages link back to the github editor.
3. There is a minimal JSON config file pages grab, which allow me to configure stuff I want for use on e.g. localhost versus github.
It works very well. I ain't sharing my code here, and you don't want it. It's about an hour's worth of hacking to rebuild yourself and working. It'd probably be another few hours before I had something worth sharing.
It works really well, and more importantly, scales pretty well. It works seamlessly as a wiki. git workflows become nice if things go from one person to many.
This is not how location hashes are meant to be used, mind you, and this breaks semantics, but it has the huge upside of running on any static web server, anywhere, including nothing but JavaScript. Until recently, it even ran on file:/// URLs, but that got nerfed a couple of years ago.
Nothing I have built there is rocket science, but it works really, really well. Including with completely non-technical people playing with my wikis.
OH! I was flummoxed. That is super clever. It breaks semantics only by convention because of the missing question mark, right? Because technically that is a valid URL.
Semantically, hashes are supposed to be used to point to different parts of a page, not to different pages. I'm breaking semantics. Lots of pages break semantics this way, though. It's a way to hack around being able to change the URL without a page reloading. That's worse for semantics, but better for performance.
It can cause issues if you're not careful. For example, if I change just the hash, the page won't reload. On the other hand, it's not hard to be careful. You listen for hashchange events, and when one comes, you reload the body of the page. Of course, the upside is that it's a lot faster that way. I don't need to refresh the whole page. I just grab a small markdown file, render it with libraries already loaded, and dump it into a div.
There are also minor issues around a11y, and around web crawlers. Again, you just want to be a little bit careful. And if you're doing this for yourself, you probably don't care about a11y or web crawlers.
On that note github needs to merge wiki has a feature rather than a tack on. http://github.com/yearoflinux/DesktopInfinity/wiki should actually be a folder rather than a separate repo. What this means is that all my contributions to wiki would be versioned and wiki won't fall out of date. Perhaps add a mechanism to auto-approve all commits that only touch the said path.
Oh man, I’ve found this sorta stuff will send me down rabbit holes for days. For whatever reason I find setting up personal knowledge bases as addicting as configuring my editor, so here’s my current drug of choice:
I have a wiki.JS instance which pulls/pushes to a got repo I have of org and markdown files. I have a keybinding attached to an elisp function (did I mention I use Emacs?) that creates or opens a templates, date-named org file with a save hooks that converts it to markdown and pushes it to my repo.
Now I have an easy way to share a page with anyone, look it up (and edit!) while I’m not on my machine, and lose _countless_ hours tweaking both my Emacs setup and wiki setup collectively.
also pointing out mdwiki here which uses .md files plus a single .html file to create a wiki, could also be used with git: http://github.com/Dynalon/mdwiki though its unmaintained for years.
[Foam](https://foambubble.github.io/foam/) is an incredible tool for a hit-based wiki. It’s a VSCode workspace you can customize endlessly, and it supports features from Obsidian, Roam, and more familiar wiki software.
I’ve been using it to try out Zettelkasten, and it really is a joy to use.
Seconding foam. You can still edit and navigate it using github/gitlab's UI, there are several functional mobile apps that work, and while not part of the official list it's trivial to get Zotero working nicely with it in both directions (embedding citations and going from citation to Zotero entry).
The foam setup can also be used very nicely with non-git syncing methods like dropbox or syncthing if you prefer.
I've thought about a similar idea; VCS backed documentation tool with an (optional) web based interface. The reason I started thinking about this problem is because of how code documentation becomes so stale so quickly.
At my job, we try to separate documentation into technical, fast changing, repo specific information in the repo Readme and "how to", reference, big picture documentation into an external tool.
We use Confluence and I have several issues with it. Primarily, the web based editor is terrible and it doesn't let you see access statistics (without a plugin, last time I checked.)
The first contributes to documentation being stale because none of the developers want to futz around with it in addition to their project Readme. The second means that you can't look at the ratio between access and last modified times.
High Access/High Modification: crucial and currently changing information that needs to be monitored for accuracy fairly regularly
Low Access/Low Modification: non crucial, but also probably no longer relevant and is cruft that could be removed.
High Access/Low Modification: important information that may be outdated and should be reviewed.
Low Access/High Modification: potentially indicates a notepad situation that could identify a "knowledge silo" with one developer.
Is there a tool that can do this sort of analysis, offers a web interface for non developers, but also allows local editing?
If you're willing to install extensions, MediaWiki has some options that you might be interested in. MediaWiki has a visual editor in addition to mark-up, my preferred way to configure it remembers which editor the user used last, but they can switch when they want. Out of the box, MediaWiki is fairly bare bones, but if you're willing to spend some time on the set-up, it's pretty powerful. For example, page views were removed in MW 1.25, but can be added back using the HitCounters[1] or WireTap[2] extensions. However, the extension I think you might like is called WatchAnalytics[3], it's able to demonstrate how "watched" a wikis pages are, who's watching them, how quickly they're reviewed after being edited, and more. It's really helpful to build a consensus at a company about what's known and provide the metrics to encourage review.
One more tip, you might try using Meza[1], an automated MediaWiki install/deployment tool to get you up and running quickly. It comes pre-baked with several extensions[2] including visual editing and the extensions I mentioned above (WireTap & WatchAnalytics). It was actually created by a talented team at NASA and makes things much easier (including suggested extensions for enterprise use) if you have access to a server.
I've been using https://www.gitbook.com/ for my personal wiki for the last year, it has a Notion-like UI and syncs changes to GitHub as markdown files.
The UI is a little buggy and much less polished than Notion and co. Though it looks nice and does the job for simple rich text.
But most importantly I don't have to worry about lockin if gitbook goes out of business, loses my data, increases their pricing, worsens the UI, or pivots to another business model - straight away I can use my text editor or the GitHub online editor.
86 comments
[ 2.0 ms ] story [ 161 ms ] thread> Ikiwiki is a wiki compiler. It converts wiki pages into HTML pages suitable for publishing on a website. Ikiwiki stores pages and history in a revision control system such as Subversion or Git. There are many other features, including support for blogging and podcasting, as well as a large array of plugins.
On the pro side, plain text will always be future-proof and basically king of platform independence. Coupling this to Git(Hub) gives you a backup of sorts, access when you are not on your main device, and cross-device syncing.
In my experience, however, several of these are overrated or unused (at least for my own use cases, but I suspect others', too). There are also many missing features. A random list: I don't really need markdown rendering, find the edit workflow of GitHub to be painful for one-liner changes, miss auto-save, find the search feature slow compared to local searches in editors, and if we're talking about a real wiki: I _really_ miss being able to paste screenshots from clipboard as an unnamed / temporary file.
So then, the question is, why bother with GitHub, and not just do this locally with VsCode / Vim / Emacs / editor of choice? And I would basically agree, and the Git/GitHub part can be added as a secondary feature. However, the article seems to be touting this part well above the rest, and my experience is quite the opposite - you rarely end up using those, or _want to_ use those.
What I still miss is auto-generation of a few features. For example, subdirectory indices, in-browser search (can be generated statically and into JS) etc. Then I think it's perfect.
gitit is a git-based wiki.
https://github.com/jgm/gitit
It's written in Haskell, which will thrill some people and annoy some people and make most people shrug.
We used gitit for more than a year, but realized that it just wasn't enough fun to use. Transitioning to Dokuwiki was fast, and it turns out to hold our interest pretty well.
You can either run it yourself or in a post-commit/push hook (or a CI action, etc). But aside from that, what do you see as the difference? Automatically adding in the navigation links?
Do the purists who object to this (in a "Linus Torvalds' definition of git kind of way") fundamentally believe that there should be no central "origin" of any kind in a repo?
Sure, the main attraction in a DVCS is that everyone has a complete copy of the code and can pull branches or integrate changes from anyone else into their work, but eventually these changes have to 'land' somewhere and for most things, that's GitHub/GitLab/whatever other hosting service with git support.
^ This is - for practical purposes - my definition of origin.
To me a wiki should have an UI on top of editable/versioned files, otherwise there is not point.
I agree with the parent poster that in this case, the UI is github, thus it's more a github wiki than a git wiki.
So if you have to optimize for an entire team you end up moving away from plain-text editing.
No one has been able to solve effectively for both use cases.
When Confluence dropped support for plain-text markup editing there was a huge storm about it. Some people are still angry at Atlassian.
https://community.atlassian.com/t5/Confluence-questions/Wiki...
Well, that is good to know at least.
I don't understand how being written in Haskell can, itself, work well or poorly or not work from the point of view of a user.
Did you mean "despite being written in Haskell", or are there usability concerns that are caused by it being written in Haskell? (... or is there some other interpretation I'm not seeing?)
https://github.com/gollum/gollum/
You can use any standard Markdown editor to manage the contents of your wiki, not just their web interface. Is great if the wiki is your source of documentation for your homelab, and need to reference it in the event of your homelab going down completely, with the raw material being just Markdown.
Post-commit hooks can be used to automatically push changes to another location (e.g. a self-hosted Gitea instance running on another host, or Gitlab, or anything else you fancy like just a file store on another host)
EDIT: to note, my primary mechanism for editing my Gollum wiki is their web interface, but having the means to use any other method too is also grand.
And it's one of very few systems that support org-mode files in addition to Markdown, although keep in mind the way Gollum links files is not quite compatible with org-mode's standard syntax.
Nowadays I just use those org files directly though, as it's just for my personal use.
If the repo has is: git@github.com:bit101/wiki_example.git
The wiki is: git@github.com:bit101/wiki_example.wiki.git
Repo: https://gitlab.com/user/example.git
Wiki: https://gitlab.com/user/example.wiki.git
https://github.com/vimwiki/vimwiki
It would make far more sense to write and commit and push only plain content, no cluttering the repository with generated markup every time.
This post is a great idea of leveraging github's own repo viewer & markdown handling. Plus they can always add their own web viewer/interface later if needed.
[0] https://github.com/zadam/trilium
1. There is an HTML file that just renders with markdown based on the hash. I know hash isn't ideal, but it was easy, and it's all static.
2. Edit buttons on rendered pages link back to the github editor.
3. There is a minimal JSON config file pages grab, which allow me to configure stuff I want for use on e.g. localhost versus github.
It works very well. I ain't sharing my code here, and you don't want it. It's about an hour's worth of hacking to rebuild yourself and working. It'd probably be another few hours before I had something worth sharing.
It works really well, and more importantly, scales pretty well. It works seamlessly as a wiki. git workflows become nice if things go from one person to many.
This sounds interesting, but I am lost. What is the hash?
If I want to render a page foo.md, I will go to:
http://server/wiki#page=foo
This is not how location hashes are meant to be used, mind you, and this breaks semantics, but it has the huge upside of running on any static web server, anywhere, including nothing but JavaScript. Until recently, it even ran on file:/// URLs, but that got nerfed a couple of years ago.
Nothing I have built there is rocket science, but it works really, really well. Including with completely non-technical people playing with my wikis.
OH! I was flummoxed. That is super clever. It breaks semantics only by convention because of the missing question mark, right? Because technically that is a valid URL.
It can cause issues if you're not careful. For example, if I change just the hash, the page won't reload. On the other hand, it's not hard to be careful. You listen for hashchange events, and when one comes, you reload the body of the page. Of course, the upside is that it's a lot faster that way. I don't need to refresh the whole page. I just grab a small markdown file, render it with libraries already loaded, and dump it into a div.
There are also minor issues around a11y, and around web crawlers. Again, you just want to be a little bit careful. And if you're doing this for yourself, you probably don't care about a11y or web crawlers.
Thanks tons.
Ok, it's just DDG, but that's the simplest solution for a static site.
I have a wiki.JS instance which pulls/pushes to a got repo I have of org and markdown files. I have a keybinding attached to an elisp function (did I mention I use Emacs?) that creates or opens a templates, date-named org file with a save hooks that converts it to markdown and pushes it to my repo.
Now I have an easy way to share a page with anyone, look it up (and edit!) while I’m not on my machine, and lose _countless_ hours tweaking both my Emacs setup and wiki setup collectively.
Drug of choice indeed.
I’ve been using it to try out Zettelkasten, and it really is a joy to use.
The foam setup can also be used very nicely with non-git syncing methods like dropbox or syncthing if you prefer.
At my job, we try to separate documentation into technical, fast changing, repo specific information in the repo Readme and "how to", reference, big picture documentation into an external tool.
We use Confluence and I have several issues with it. Primarily, the web based editor is terrible and it doesn't let you see access statistics (without a plugin, last time I checked.)
The first contributes to documentation being stale because none of the developers want to futz around with it in addition to their project Readme. The second means that you can't look at the ratio between access and last modified times.
High Access/High Modification: crucial and currently changing information that needs to be monitored for accuracy fairly regularly
Low Access/Low Modification: non crucial, but also probably no longer relevant and is cruft that could be removed.
High Access/Low Modification: important information that may be outdated and should be reviewed.
Low Access/High Modification: potentially indicates a notepad situation that could identify a "knowledge silo" with one developer.
Is there a tool that can do this sort of analysis, offers a web interface for non developers, but also allows local editing?
[1] https://www.mediawiki.org/wiki/Extension:HitCounters
[2] https://www.mediawiki.org/wiki/Extension:Wiretap
[3] https://www.mediawiki.org/wiki/Extension:WatchAnalytics
[1] https://www.mediawiki.org/wiki/Meza
[2] https://www.mediawiki.org/wiki/Meza/Extensions_installed_by_...
The UI is a little buggy and much less polished than Notion and co. Though it looks nice and does the job for simple rich text.
But most importantly I don't have to worry about lockin if gitbook goes out of business, loses my data, increases their pricing, worsens the UI, or pivots to another business model - straight away I can use my text editor or the GitHub online editor.
Git is a great fit for wikis!