Hacker News new | past | comments | ask | show | jobs | submit login
Git-Based Wiki (bit-101.com)
136 points by ingve 10 months ago | hide | past | favorite | 83 comments

That's not a git-based wiki. That's a GitHub-based wiki.

gitit is a git-based wiki.


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.

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.

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.

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 is using GitHub's markdown renderer so that links are clickable.

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.


It's a lock-in nightmare to migrate, and it really needs to be accounted for as a deep cost in choosing Confluence.

dokuwiki is plain text too

And Github already has Wikis built in (https://docs.github.com/en/github/building-a-strong-communit...). It's basically the same as what the OP is proposing, but with more explicit support (history/sidebar rendered in the Github UI)

Private GH wikis are not available on the free tier

https://wiki.snowdrift.coop uses gitit.. But, a patched version that has bidirectional sync with https://gitlab.com/snowdrift/wiki (pushes after commits, pulls when promoted by the gitlab webhook). Works pretty well.

A static site generator isn't really the same thing as a git-based wiki.

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?

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

Well, that is good to know at least.

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.

I also keep it local, with vimwiki: https://github.com/vimwiki/vimwiki

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.

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!

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


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

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

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.

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

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

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

Thanks for the tip!

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

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

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

What hasn't been mentioned is the Zim desktop wiki: 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). 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/), 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.

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.

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.

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

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

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.

Git is a great fit for wikis!

Gitbooks search is also absolutely best in class.

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.

That makes sense. Thank you for the clarity :)

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 took the plunge a week ago to go for org mode & spacemacs, worth it.

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.

Check out organice. https://organice.200ok.ch/

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.

Been using 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.

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

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.

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.

> renders with markdown based on the hash.

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

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:


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.

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

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.

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

Thanks tons.

Gitlab has this for a while already https://docs.gitlab.com/ee/user/project/wiki/

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.

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.

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

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.

With mermaid digrams, formulas etc

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 .

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

ikiwiki gives you a wiki with git as backend.

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.

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.

People have been doing this for a while:


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

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.

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.

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

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.

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.

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

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

My blog has a search: https://jlelse.blog/search/

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

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

Where is the wiki part?

Use vimwiki and commit it to git, done.


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



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.

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

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


Applications are open for YC Winter 2022

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact