
Git-Based Wiki - ingve
https://www.bit-101.com/blog/2020/09/git-based-wiki/
======
dsr_
That's not a git-based wiki. That's a GitHub-based wiki.

gitit is a git-based wiki.

[https://github.com/jgm/gitit](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.

~~~
chrismorgan
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.

~~~
Galanwe
With your definition of wiki, any versioned text file is one...

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.

------
danielbarla
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.

~~~
rich_sasha
Yeah, doing it locally is my way too.

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.

~~~
tmpfs
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!

------
type0
Gollum wiki uses git, you can edit it via web interface and selfhost on your
own network

[https://github.com/gollum/gollum/](https://github.com/gollum/gollum/)

~~~
oarsinsync
+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.

~~~
alpaca128
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.

------
h4kor
FYI: GitHub wikis are also git repositories

If the repo has is: git@github.com:bit101/wiki_example.git

The wiki is: git@github.com:bit101/wiki_example.wiki.git

~~~
cdesai
The same works for GitLab too.

Repo:
[https://gitlab.com/user/example.git](https://gitlab.com/user/example.git)

Wiki:
[https://gitlab.com/user/example.wiki.git](https://gitlab.com/user/example.wiki.git)

------
fuball63
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?

~~~
Ninjaneered
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.

[1]
[https://www.mediawiki.org/wiki/Extension:HitCounters](https://www.mediawiki.org/wiki/Extension:HitCounters)

[2]
[https://www.mediawiki.org/wiki/Extension:Wiretap](https://www.mediawiki.org/wiki/Extension:Wiretap)

[3]
[https://www.mediawiki.org/wiki/Extension:WatchAnalytics](https://www.mediawiki.org/wiki/Extension:WatchAnalytics)

~~~
fuball63
Thanks for the tip!

~~~
Ninjaneered
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.

[1] [https://www.mediawiki.org/wiki/Meza](https://www.mediawiki.org/wiki/Meza)

[2]
[https://www.mediawiki.org/wiki/Meza/Extensions_installed_by_...](https://www.mediawiki.org/wiki/Meza/Extensions_installed_by_default)

------
brentjanderson
[Foam]([https://foambubble.github.io/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.

~~~
vorpalhex
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.

------
jnxx
What hasn't been mentioned is the Zim desktop wiki: [https://zim-
wiki.org/](https://zim-wiki.org/)

It as a lot of good ideas: It automatically creates new pages when following
links for which a page does not exist yet. It also allows to arrange pages in
sub-pages which are grouped in folders. And, what I think is really good for
organizing, is it allows to rename pages, and automatically fixes the links
which are affected by this.

What I see as a disadvantage and does not fits my needs is that it uses an own
markup format. I need reStructuredText / reSt markup (which can also be
rendered by github), specifically for program documentation. reStructuredText
is more suited for longer documentation, it has better code formatting, can
show tables of contents, and is also less tied to output in a HTML page (it
can easily be converted to a LaTeX or PDF document). I see a big value in
being able to collect information in the same markup format as will be used
for final code or API documentation, this reduces friction.

Zim allows to export reStructuredText, but currently this does only work
partially.

What I use instead is a reStructuredText editor which is a Python app which is
called retext ([https://github.com/retext-
project/retext](https://github.com/retext-project/retext)). It allows to enter
text and preview it quickly, and to follow any links. reStructuredText also
allows to view pages in a browser using restview
([https://pypi.org/project/restview/](https://pypi.org/project/restview/)),
similar to gitit or grip for Markdown.

What I still miss is the capability to quickly create and open new links, as
Zim or vimwiki can do. This is an option which is sorely missing in retext. I
think for people who have similar needs but do not need the stronger
structuring of reStructuredText, vimwiki is perhaps a very good option.

------
mttyng
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.

Drug of choice indeed.

------
banana_giraffe
I've been running a git-based wiki for while now running on AWS Codecommit and
using a API Gateway in front of a Lambda as a front end.

The main features that keep me using it:

The main "todo" page is presented as a web page with a series of dismissable
links and has a simple textbox to add a new line. It lets me manage the todo
items with nothing more than a browser, so there's zero friction. On most of
my browsers it's now my home page.

There's a back-end process that reads a yaml file and adds tasks once a day.
This helps me keep tasks for a future date and get to a "zero todo items" for
today. And I've made adding future tasks as friction free as possible. I can
enter "tomorrow", or "three weeks", or several other easy free form entry
formats for the date. Since I control it, if I try to enter something it
doesn't understand, I can teach it by modifying a python module that's checked
in next to the yaml file.

I have pages for todo-items for work, links I want to check out when I have
free time, and pages for notes in a traditional wiki. I even have a custom
page to make it easy to enter some medical stats my doctor wants me to track,
along with a todo task that shows up to remind me.

And since it's all git based, I can go back in time if I need to, never worry
about it disappearing. On a PC I have the full power of a real git client and
a real text editor. I'm really happy with it.

I should clean it up and offer it for others.

~~~
dreamer7
Seems like a good setup! Let us know if you ever make it open source. I would
like to try it

------
Peckingjay
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.

[0] [https://github.com/zadam/trilium](https://github.com/zadam/trilium)

------
bckygldstn
I've been using [https://www.gitbook.com/](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.

Git is a great fit for wikis!

~~~
alexktz
Gitbooks search is also absolutely best in class.

------
sega_sai
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

~~~
dllthomas
> 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?)

~~~
sega_sai
I wanted to implement a feature, like seing the most recent changes time, or
fix a bug
[https://github.com/jgm/gitit/pull/388](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.

~~~
dllthomas
That makes sense. Thank you for the clarity :)

------
fouc
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.

------
blablablerg
I took the plunge a week ago to go for org mode & spacemacs, worth it.

~~~
sleavey
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.

~~~
timpark
Check out organice. [https://organice.200ok.ch/](https://organice.200ok.ch/)

------
DavidPP
Been using [https://www.dendron.so/](https://www.dendron.so/) for a total of
... 12h.

It's been mentionned here a couple of days ago actually. It's built on top of
Vscode and use pure md files, so can be synced with Git or be built as github
page.

~~~
transfire
Looks nice, but I take it is only geared for a single user. How would multiple
simultaneous users fair?

------
languagehacker
Reinvention of the wheel aside, I'd like to point out that MediaWiki used a
hash-based, (relatively) immutable history for edits before Git was even a
thing. Git is highly FS-optimized, but it's amazing how similar MediaWiki's
history management data structures are.

------
murgindrag
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.

~~~
tomcam
> renders with markdown based on the hash.

This sounds interesting, but I am lost. What is the hash?

~~~
murgindrag
Oh. Sorry. Overloaded term. URL location hash, not git hash. To see it, type
`location.hash` in your browser's JavaScript console.

If I want to render a page foo.md, I will go to:

[http://server/wiki#page=foo](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.

~~~
tomcam
> URL location hash, not git hash

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.

~~~
murgindrag
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.

~~~
tomcam
OK that was a world class education in 3 paragraphs! Making my own Markdown-
based CMS so this was gold.

Thanks tons.

------
ac42
Gitlab has this for a while already
[https://docs.gitlab.com/ee/user/project/wiki/](https://docs.gitlab.com/ee/user/project/wiki/)

------
rphln
Recently, I've started a personal wiki with Git, Jekyll and the Just the Docs
theme (for built-in search on the rendered pages).

It's a fairly standard setup in which each page is just a post, and the index
is automatically generated by Jekyll (this makes it slightly more inconvenient
to use with Vim, but appeals to my laziness).

Some things I considered doing eventually were:

* Using Rmarkdown or something else to evaluate/render code blocks and Graphviz diagrams.

* Implement a pingback mechanism -- if page B has a link to page A, then B shows up as a related page while viewing A.

Though I want to avoid going into those rabbit holes for now, as it's still
too early.

------
yearoflinux
On that note github needs to merge wiki has a feature rather than a tack on.
[http://github.com/yearoflinux/DesktopInfinity/wiki](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.

------
yumraj
WikiJs supports markdown and a bidirectional sync with github, to effectively
provide a rather featured git-synced wiki.

Depending on how it's used, it can even become a git-based wiki

------
geordee
Azure DevOps Wiki is a Git repo at the heart of it. They have built an editor
and rendering layer on top of a git repo of markdown documents and image
assets.

~~~
rathish_g
With mermaid digrams, formulas etc

------
gramakri
[https://github.com/claudioc/jingo](https://github.com/claudioc/jingo) is one
of the first apps we packaged for cloudron. You can git push markdown files or
edit with the web ui. It's primarily single user and has no sharing or access
control but does support auth. In fact, lots of our docs are still there .

------
kevinslin
I've found that its hard to beat plaintext markdown notes with git. been
taking notes like this for the past ten years and now have 10k+ markdown
notes. just launched a markdown note taking plugin built on top of vscode to
help with this sort of workflow: [https://dendron.so](https://dendron.so)

------
mlang23
ikiwiki gives you a wiki with git as backend.

~~~
smkellat
ikiwiki has been around for over a decade. You can even pay for a hosted
version of it at branchable. It is kinda sad how much people overlook it.

~~~
johnisgood
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.

------
bitlax
People have been doing this for a while:

[https://github.com/sindresorhus/awesome](https://github.com/sindresorhus/awesome)

I had markdown-based notes for a while before I switched to Org-mode but I
guess that comes down to personal preference.

~~~
iNate2000
Me too!

But recently I learned that Emacs markdown-mode has wiki-links-mode which
let’s me use `[[file]]` to link to `file.md` and it creates it if it doesn’t
exist.

------
bachmeier
A couple comments:

1\. Gitlab works well for this because it comes with a nice online IDE. No
need to leave the browser, which is especially helpful if using a Chromebook
or tablet, yet you still own your data and can pull locally.

2\. Fossil comes with a markdown wiki built in, and it can be extended.

------
DarkContinent
Do you ever need to update your wiki from a mobile device? If so, how is the
experience?

------
heresie-dabord
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.

------
carl_dr
How is this better than a notes app that has some cloud syncing?

Editing Markdown and committing to a Git repo is a PITA on mobile, and a lot
of the time, I want to add to a shopping list or add a movie to watch when I’m
out and about.

------
jlelse
That's pretty similar to my Wiki approach: [https://jlelse.blog/posts/wiki-
approach/](https://jlelse.blog/posts/wiki-approach/)

~~~
alexktz
It's clear to read, I like this one overall. Simple. But it would benefit
greatly from search.

~~~
jlelse
My blog has a search:
[https://jlelse.blog/search/](https://jlelse.blog/search/)

Ok, it's just DDG, but that's the simplest solution for a static site.

------
aashu_dwivedi
I keep my emacs org files in a repo. Which is pretty much the same thing.

------
throwaway316943
Use vimwiki and commit it to git, done.

[https://github.com/vimwiki/vimwiki](https://github.com/vimwiki/vimwiki)

------
DINKDINK
also see git-based blogs (strong publisher authentication via pgp signing
commits)

[https://blog.invisiblethings.org/2015/02/09/my-new-git-
based...](https://blog.invisiblethings.org/2015/02/09/my-new-git-based-
blog.html)

[https://laanwj.github.io/about/](https://laanwj.github.io/about/)

------
littlecranky67
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](http://github.com/Dynalon/mdwiki) though
its unmaintained for years.

------
INTPenis
Mkdocs+git repo+CD pipeline and you have yourself a git-based markdown wiki.

------
Havoc
Where is the wiki part?

------
aerojoe23
wiki.js can be set up to import and export to a git repo. It supports
markdown.

------
wow_yes
Based?

