Git-Based Wiki
bit-101.com
bit-101.com
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.
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.
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.
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
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
[1] https://www.mediawiki.org/wiki/Meza
[2] https://www.mediawiki.org/wiki/Meza/Extensions_installed_by_...
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.
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.
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.
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.
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!
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?)
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.
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.
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:
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.
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.
Depending on how it's used, it can even become a git-based wiki
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.
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.
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.
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.
Ok, it's just DDG, but that's the simplest solution for a static site.
https://blog.invisiblethings.org/2015/02/09/my-new-git-based...
> 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.