7 ms·

Gollum – A simple, Git-powered wiki with a sweet API and local frontend

238 points by dsr12 5y ago

ketzo 5y ago
I like the look of this a lot, particularly the support for running-from-local. I think git is such an ideal backend for something like a wiki, where multiple contributors and version history are both so important. Tangent: how do HN folks generally do technical wikis -- or really, just keep track of the technical details of your software -- in large software development organizations? My org uses Confluence for some stuff, Github pages and READMEs for others. It's... fine. It's not the worst I've ever seen, you can find some useful stuff with a little bit of work and some knowledge about where to look, but it's still very likely that whatever you're reading is either outdated or now-irrelevant. How do you (and your team) solve the challenge of keeping documentation actually relevant and up-to-date when there are so many people writing so much code, then leaving two years later?
- onei 5y ago
  I always find Confluence to be the place where docs go to die. There's very little motivation to keep it up to date and tends to be one or two people driving it. When they move to another team or job, then it gets abandoned. The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API docs). The last two in particular have become a big part of the design process, so it's been bought into heavily. Whether those stand the test of time remains to be seen - they're relatively new.
  - epage 5y ago
    My problem with docs in repos is it isn't as smooth to edit, especially if you have to wait for reviews.
    - monocasa 5y ago
      You can always just make the semantics of the doc folder or repo push permissions match what you're looking for, ie. 'no real reviews necessary to push to master' if that's the semantics you're looking for.
    - ketzo 5y ago
      I agree that this is actually a much bigger deal than it would initially seem. Any kind of friction is a huge problem when it comes to a task that people are already sort of reluctant to do; just the thought of "ah, fuck, I gotta get two reviews just to add a couple lines of setup instructions?" makes people way less likely to update repo docs as frequently as they need to.
  - FalconSensei 5y ago
    > I always find Confluence to be the place where docs go to die Yeah... I'm not a big fan either. Currently in my team we just use google docs for more dynamic stuff, and have a wiki page with links to all docs. Otherwise we know that people won't bother editing
    - nivertech 5y ago
      I remember seeing somewhere GDoc to Markdown converter. After the initial discussion is finished, the Google doc can be converted to the [Github-flavored] Markdown and stored in the [Github] repo. It would be a good idea to create an initial GDoc based on the markdown template from the repo. Frankly with the speed of Github innovation, they will be adding GDoc-like commenting and collaboration soon. Not sure how it can be integrated with git branches though.
  - NortySpock 5y ago
    To me Confluence's problem is the not-very-relevant search, which either gives me generic blank documents that someone created as a placeholder (?!? -- I've started suffixing these with (blank)) or fails to find synonyms or related words when I can't quite come up with the exact search term (wonder if these "related words or synonyms" could be manually added...) I'm sure it is a difficult problem but I haven't really found any good solutions other than "make really long titles that use many words to describe the content" or "Add lots of tags" and even them I'm not sure it helps or not. Does the search take into account click-through rate? Link count?
    - svcrunch 5y ago
      > gives me generic blank documents that someone created as a placeholder ... fails to find synonyms or related words ... Add lots of tags These kinds of problems can be solved using neural networks as the foundation for search (variously termed "neural information retrieval" and "semantic search"). I worked on this at Google Research from 2016-2020, before launching ZIR AI in 2020 to make neural search available as a PaaS, just like Elasticsearch and Algolia have done for keyword matching. Here are a couple of introductory pieces if you're interested in learning more: [1] https://blog.zir-ai.com/the-high-cost-of-keyword-search https://blog.zir-ai.com/the-high-cost-of-keyword-search, "The High Cost of Keyword Search" [2] https://blog.zir-ai.com/semantic-search-helps-chatbots-answer-more-questions https://blog.zir-ai.com/semantic-search-helps-chatbots-answe... "Semantic search helps chatbots answer more questions"
    - truenindb 5y ago
      confluence's main problem is that it is being used by enterprise software people doing enterprise software baloney.
  - AmpsterMan 5y ago
    I concur about confluence being where things die. There's a dev on our team that is very big on confluence whereas I'm not. Ironically, I am big on documenting our public methods from the perspective of a user of our library whereas he puts javadocs on private methods. He has more experience than I do, so I don't fight him on it, but man do I find it futile.
- pkrotich 5y ago
  We use self-hosted Readthedocs [0] with git/repo integration - merge to master triggers a build. [0] https://readthedocs.org/ https://readthedocs.org/
- sneak 5y ago
  Gitea supports web-based wikis that are git repos on the backend. It also has a good auth system and supports U2F (or SSO).
  - tga 5y ago
    Unless that has changed recently, gitea doesn’t provide any way to search a wiki (!), making it quite useless for documentation.
- sillysaurusx 5y ago
  Notion.
  - Matrixik 5y ago
    I would love to have something like Notion but using git for all data storage and edit history. There is https://stackedit.io/ https://stackedit.io/ offering it but I stopped using it because of bugs when trying to edit on mobile. And it basically abandoned for the last 2 years https://github.com/benweet/stackedit https://github.com/benweet/stackedit (only some deps updates, nothing more).
- polote 5y ago
  There is only one way to make documention works. This is to have everyone following the same standards. This is not enough of course. You can have different people using different tools to write it, but all those documents needs to be referenced at the same place and be searchable at least by title. There is no magic tool this is first a people/process problem If your org has several place to find it and no strategy. Then the first step is to have a documentation strategy. That will not solve all your issues, but without it you are going to be very limited
- codazoda 5y ago
  I use GitHub wiki’s but they’re not perfect and I think about this a lot. I’ve been thinking about building something like Slack but for documentation instead of conversation. A git repo is a great way to store your files so that you have history, backups, and avoid vendor lock-in.
- pmontra 5y ago
  I like to write docs with Jekyll in the same repository of the code, not in separate repository as in GitHub. In this way I can document the changes in a feature branch and leave unchanged the docs in the release branch. Then the changes get merged when we release the feature. A customer of mine writes documentation in Google Sites (horrible UX and not for for this task, they eventually realized it) and my pages (Bitbucket) are linked from the table of contents (release branch). To read the documentation for a new feature one must know the name of the feature branch.
ducktective 5y ago
Interesting! Isn't it better to couple the documentation of a project to the source (e.g. in a `docs/` sub-directory) and just use markdown?
- chrisweekly 5y ago
  Yep. GitLab's support for Mermaid in markdown is pretty nice. I'm looking into making my experiments with a Kroki server more official, at which point we'll have a robust platform for markdown-based, repo-internal, embedded-diagram-supporting docs.
- codazoda 5y ago
  My docs often end up being related to multiple repos. So, although I want my docs in git, I’d prefer them to be their own repo.
throwaway81523 5y ago
I've used gitit and it is pretty nice. Why do we need another one of these?
- yodon 5y ago
  > gitit is pretty nice. Why do we need another one of these? Gollum and Gitit have both been around for more than a decade. Thousands of stars, hundreds of forks, and active commit histories spanning more than ten years suggests the world views both as of value.
  - throwaway81523 5y ago
    If this program has been around for 10 years, then unless there is some news about it, it should have (2011) or whatever in the link title.
deleted 5y ago
[deleted]
ak217 5y ago
If you're new to Gollum, it's the software that powers GitHub's wiki tab in the repo view. Gollum was one of the first Markdown wikis and still is a fantastic choice for running a Git Markdown-powered wiki. I ran a number of technical documentation sites on Gollum, and one of the things that set it apart was hackability. It was easy to modify it to do very custom things based on our site's needs.
- codazoda 5y ago
  Are you sure? This statement in the docs makes it sound like it’s more of a clone. > Gollum strives to be compatible with GitHub wikis (see --lenient-tag-lookup) Edit: Looks like the answer is yes if you look at just /gollum. > Gollum is a simple wiki system built on top of Git that powers GitHub Wikis.
mojombo 5y ago
Fun to see this on HN! I originally created Gollum to power GitHub's wiki system and wanted to see if we could use Git to make our wikis more powerful AND more open. I thought it would be cool if you could just clone your GitHub wiki and modify it locally or export it to some other system if you needed, or have it all locally for an airplane trip without wifi. Another interesting thing is that I used my Readme Driven Development method to develop it, which you can see in the Readme of the first commit: https://github.com/gollum/gollum/commit/c7875704971be998a5399ce83e66a5dada03aad4 https://github.com/gollum/gollum/commit/c7875704971be998a539.... I wrote it before writing a single line of code and found it worked nicely to figure out the API and feel out the ergonomics of the text format. More on that approach here: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve... Glad to see the project alive and well!
- austinjp 5y ago
  I never knew that my default approach is called readme-driven development :)
  - bombela 5y ago
    I guess building from specifications is so rare in software, we forgot how it's called.
    - nivertech 5y ago
      nano-waterfall (nWF) - README.md -Driven Development micro-waterfall (μWF) - ARCHITECTURE.md -Driven Development mini-waterfall (mWF) - plan→build (iterate)→ship full waterfool (FWF) - "you went full waterfool, never go full waterfool"
- xrd 5y ago
  I had forgotten you wrote both Jekyll *and* Gollum. I'm writing the next generation of Jekyll, called Svekyll, which is Jekyll plus Svelte: "the radical simplicity of Jekyll + the futuristic power of Svelte" https://svekyll.com https://svekyll.com I know it has been hard for you to get in on the ground floor of things, but this is your chance if you want to invest. I'm building a publishing company with Svekyll as the starting point, but with a few extra twists coming soon. Could we jump on a call and I'll share the roadmap?
MrStonedOne 5y ago
So many versions and rewrites of wikis. github even has their own wiki system. None of them support pull requests. (wikipedia supports patch/diff style manual change requests done via talk pages which is sorta gets you there, but not quite the github style automated pull request work flow i'd love to see supported) Its honestly a shame.
- deleted 5y ago
  [deleted]
truenindb 5y ago
how about a running instance of this thing to look at if it is so great
dcchambers 5y ago
I have a strange obsession with git-powered wikis. I've spent time playing around with most of the popular ones and I think it's basically the perfect documentation format. However they all have their quirks and each one seems to be missing some major feature I want and it takes an unreal amount of self-control for me to not just throw my hands up and create my own, adding yet another one to the mix.
xrd 5y ago
I wrote a book for O'Reilly about GitHub and their API and for some reason no one noticed that we added a chapter on Gollum (there isn't an API to access Gollum on github). It was the weakest one of the chapters, IMHO, but, you know, deadlines. O'Reilly was gracious enough to release it under CC, so you can read that chapter (and the whole book actually) here: https://buildingtoolswithgithub.teddyhyde.io/chapter-03-gollum.html https://buildingtoolswithgithub.teddyhyde.io/chapter-03-goll... There is a section on using Rugged, the ruby git library and how you can use that with Gollum. https://buildingtoolswithgithub.teddyhyde.io/chapter-03-gollum.html#using-the-rugged-library https://buildingtoolswithgithub.teddyhyde.io/chapter-03-goll... While writing this book, I found it really fascinating to learn about how git works by trying to manage a Gollum wiki. For example, if you add an image to multiple places in a repository, it only needs to store it once because git can tell it is already in there. https://buildingtoolswithgithub.teddyhyde.io/chapter-03-gollum.html#optimizing-for-image-storage https://buildingtoolswithgithub.teddyhyde.io/chapter-03-goll...
misterdata 5y ago
Wiki.js [1] is quite mature and nice as well, supporting bidirectional Git sync, a GraphQL api and search! [1] https://js.wiki/ https://js.wiki/
block_dagger 5y ago
I’ve been using Gollum on my local machine for personal wikis and it’s great!
pkulak 5y ago
This was a fun weekend project. Thanks! I will say, however, that getting it running took minutes; getting auth running was nearly a full day. Just HTTP Basic auth had me writing Ruby, then giving up and using a library that hasn't seen a single commit in years.
ptman 5y ago
Is there anything other than ikiwiki which works as a "wiki compiler" producing static html?

238 points by dsr12 5y ago

I like the look of this a lot, particularly the support for running-from-local. I think git is such an ideal backend for something like a wiki, where multiple contributors and version history are both so important. Tangent: how do HN folks generally do technical wikis -- or really, just keep track of the technical details of your software -- in large software development organizations? My org uses Confluence for some stuff, Github pages and READMEs for others. It's... fine. It's not the worst I've ever seen, you can find some useful stuff with a little bit of work and some knowledge about where to look, but it's still very likely that whatever you're reading is either outdated or now-irrelevant. How do you (and your team) solve the challenge of keeping documentation actually relevant and up-to-date when there are so many people writing so much code, then leaving two years later?

onei 5y ago
I always find Confluence to be the place where docs go to die. There's very little motivation to keep it up to date and tends to be one or two people driving it. When they move to another team or job, then it gets abandoned. The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API docs). The last two in particular have become a big part of the design process, so it's been bought into heavily. Whether those stand the test of time remains to be seen - they're relatively new.
- epage 5y ago
  My problem with docs in repos is it isn't as smooth to edit, especially if you have to wait for reviews.
  - monocasa 5y ago
    You can always just make the semantics of the doc folder or repo push permissions match what you're looking for, ie. 'no real reviews necessary to push to master' if that's the semantics you're looking for.
  - ketzo 5y ago
    I agree that this is actually a much bigger deal than it would initially seem. Any kind of friction is a huge problem when it comes to a task that people are already sort of reluctant to do; just the thought of "ah, fuck, I gotta get two reviews just to add a couple lines of setup instructions?" makes people way less likely to update repo docs as frequently as they need to.
- FalconSensei 5y ago
  > I always find Confluence to be the place where docs go to die Yeah... I'm not a big fan either. Currently in my team we just use google docs for more dynamic stuff, and have a wiki page with links to all docs. Otherwise we know that people won't bother editing
  - nivertech 5y ago
    I remember seeing somewhere GDoc to Markdown converter. After the initial discussion is finished, the Google doc can be converted to the [Github-flavored] Markdown and stored in the [Github] repo. It would be a good idea to create an initial GDoc based on the markdown template from the repo. Frankly with the speed of Github innovation, they will be adding GDoc-like commenting and collaboration soon. Not sure how it can be integrated with git branches though.
- NortySpock 5y ago
  To me Confluence's problem is the not-very-relevant search, which either gives me generic blank documents that someone created as a placeholder (?!? -- I've started suffixing these with (blank)) or fails to find synonyms or related words when I can't quite come up with the exact search term (wonder if these "related words or synonyms" could be manually added...) I'm sure it is a difficult problem but I haven't really found any good solutions other than "make really long titles that use many words to describe the content" or "Add lots of tags" and even them I'm not sure it helps or not. Does the search take into account click-through rate? Link count?
  - svcrunch 5y ago
    > gives me generic blank documents that someone created as a placeholder ... fails to find synonyms or related words ... Add lots of tags These kinds of problems can be solved using neural networks as the foundation for search (variously termed "neural information retrieval" and "semantic search"). I worked on this at Google Research from 2016-2020, before launching ZIR AI in 2020 to make neural search available as a PaaS, just like Elasticsearch and Algolia have done for keyword matching. Here are a couple of introductory pieces if you're interested in learning more: [1] https://blog.zir-ai.com/the-high-cost-of-keyword-search https://blog.zir-ai.com/the-high-cost-of-keyword-search, "The High Cost of Keyword Search" [2] https://blog.zir-ai.com/semantic-search-helps-chatbots-answer-more-questions https://blog.zir-ai.com/semantic-search-helps-chatbots-answe... "Semantic search helps chatbots answer more questions"
  - truenindb 5y ago
    confluence's main problem is that it is being used by enterprise software people doing enterprise software baloney.
- AmpsterMan 5y ago
  I concur about confluence being where things die. There's a dev on our team that is very big on confluence whereas I'm not. Ironically, I am big on documenting our public methods from the perspective of a user of our library whereas he puts javadocs on private methods. He has more experience than I do, so I don't fight him on it, but man do I find it futile.
pkrotich 5y ago
We use self-hosted Readthedocs [0] with git/repo integration - merge to master triggers a build. [0] https://readthedocs.org/ https://readthedocs.org/
sneak 5y ago
Gitea supports web-based wikis that are git repos on the backend. It also has a good auth system and supports U2F (or SSO).
- tga 5y ago
  Unless that has changed recently, gitea doesn’t provide any way to search a wiki (!), making it quite useless for documentation.
sillysaurusx 5y ago
Notion.
- Matrixik 5y ago
  I would love to have something like Notion but using git for all data storage and edit history. There is https://stackedit.io/ https://stackedit.io/ offering it but I stopped using it because of bugs when trying to edit on mobile. And it basically abandoned for the last 2 years https://github.com/benweet/stackedit https://github.com/benweet/stackedit (only some deps updates, nothing more).
polote 5y ago
There is only one way to make documention works. This is to have everyone following the same standards. This is not enough of course. You can have different people using different tools to write it, but all those documents needs to be referenced at the same place and be searchable at least by title. There is no magic tool this is first a people/process problem If your org has several place to find it and no strategy. Then the first step is to have a documentation strategy. That will not solve all your issues, but without it you are going to be very limited
codazoda 5y ago
I use GitHub wiki’s but they’re not perfect and I think about this a lot. I’ve been thinking about building something like Slack but for documentation instead of conversation. A git repo is a great way to store your files so that you have history, backups, and avoid vendor lock-in.
pmontra 5y ago
I like to write docs with Jekyll in the same repository of the code, not in separate repository as in GitHub. In this way I can document the changes in a feature branch and leave unchanged the docs in the release branch. Then the changes get merged when we release the feature. A customer of mine writes documentation in Google Sites (horrible UX and not for for this task, they eventually realized it) and my pages (Bitbucket) are linked from the table of contents (release branch). To read the documentation for a new feature one must know the name of the feature branch.

ducktective 5y ago

Interesting! Isn't it better to couple the documentation of a project to the source (e.g. in a `docs/` sub-directory) and just use markdown?

chrisweekly 5y ago
Yep. GitLab's support for Mermaid in markdown is pretty nice. I'm looking into making my experiments with a Kroki server more official, at which point we'll have a robust platform for markdown-based, repo-internal, embedded-diagram-supporting docs.
codazoda 5y ago
My docs often end up being related to multiple repos. So, although I want my docs in git, I’d prefer them to be their own repo.

throwaway81523 5y ago

I've used gitit and it is pretty nice. Why do we need another one of these?

yodon 5y ago
> gitit is pretty nice. Why do we need another one of these? Gollum and Gitit have both been around for more than a decade. Thousands of stars, hundreds of forks, and active commit histories spanning more than ten years suggests the world views both as of value.
- throwaway81523 5y ago
  If this program has been around for 10 years, then unless there is some news about it, it should have (2011) or whatever in the link title.

deleted 5y ago

[deleted]

ak217 5y ago

If you're new to Gollum, it's the software that powers GitHub's wiki tab in the repo view. Gollum was one of the first Markdown wikis and still is a fantastic choice for running a Git Markdown-powered wiki. I ran a number of technical documentation sites on Gollum, and one of the things that set it apart was hackability. It was easy to modify it to do very custom things based on our site's needs.

codazoda 5y ago
Are you sure? This statement in the docs makes it sound like it’s more of a clone. > Gollum strives to be compatible with GitHub wikis (see --lenient-tag-lookup) Edit: Looks like the answer is yes if you look at just /gollum. > Gollum is a simple wiki system built on top of Git that powers GitHub Wikis.

mojombo 5y ago

Fun to see this on HN! I originally created Gollum to power GitHub's wiki system and wanted to see if we could use Git to make our wikis more powerful AND more open. I thought it would be cool if you could just clone your GitHub wiki and modify it locally or export it to some other system if you needed, or have it all locally for an airplane trip without wifi. Another interesting thing is that I used my Readme Driven Development method to develop it, which you can see in the Readme of the first commit: https://github.com/gollum/gollum/commit/c7875704971be998a5399ce83e66a5dada03aad4 https://github.com/gollum/gollum/commit/c7875704971be998a539.... I wrote it before writing a single line of code and found it worked nicely to figure out the API and feel out the ergonomics of the text format. More on that approach here: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve... Glad to see the project alive and well!

austinjp 5y ago
I never knew that my default approach is called readme-driven development :)
- bombela 5y ago
  I guess building from specifications is so rare in software, we forgot how it's called.
  - nivertech 5y ago
    nano-waterfall (nWF) - README.md -Driven Development micro-waterfall (μWF) - ARCHITECTURE.md -Driven Development mini-waterfall (mWF) - plan→build (iterate)→ship full waterfool (FWF) - "you went full waterfool, never go full waterfool"
xrd 5y ago
I had forgotten you wrote both Jekyll *and* Gollum. I'm writing the next generation of Jekyll, called Svekyll, which is Jekyll plus Svelte: "the radical simplicity of Jekyll + the futuristic power of Svelte" https://svekyll.com https://svekyll.com I know it has been hard for you to get in on the ground floor of things, but this is your chance if you want to invest. I'm building a publishing company with Svekyll as the starting point, but with a few extra twists coming soon. Could we jump on a call and I'll share the roadmap?

MrStonedOne 5y ago

So many versions and rewrites of wikis. github even has their own wiki system. None of them support pull requests. (wikipedia supports patch/diff style manual change requests done via talk pages which is sorta gets you there, but not quite the github style automated pull request work flow i'd love to see supported) Its honestly a shame.

deleted 5y ago
[deleted]

truenindb 5y ago

how about a running instance of this thing to look at if it is so great

dcchambers 5y ago

I have a strange obsession with git-powered wikis. I've spent time playing around with most of the popular ones and I think it's basically the perfect documentation format. However they all have their quirks and each one seems to be missing some major feature I want and it takes an unreal amount of self-control for me to not just throw my hands up and create my own, adding yet another one to the mix.

xrd 5y ago

I wrote a book for O'Reilly about GitHub and their API and for some reason no one noticed that we added a chapter on Gollum (there isn't an API to access Gollum on github). It was the weakest one of the chapters, IMHO, but, you know, deadlines. O'Reilly was gracious enough to release it under CC, so you can read that chapter (and the whole book actually) here: https://buildingtoolswithgithub.teddyhyde.io/chapter-03-gollum.html https://buildingtoolswithgithub.teddyhyde.io/chapter-03-goll... There is a section on using Rugged, the ruby git library and how you can use that with Gollum. https://buildingtoolswithgithub.teddyhyde.io/chapter-03-gollum.html#using-the-rugged-library https://buildingtoolswithgithub.teddyhyde.io/chapter-03-goll... While writing this book, I found it really fascinating to learn about how git works by trying to manage a Gollum wiki. For example, if you add an image to multiple places in a repository, it only needs to store it once because git can tell it is already in there. https://buildingtoolswithgithub.teddyhyde.io/chapter-03-gollum.html#optimizing-for-image-storage https://buildingtoolswithgithub.teddyhyde.io/chapter-03-goll...

misterdata 5y ago

Wiki.js [1] is quite mature and nice as well, supporting bidirectional Git sync, a GraphQL api and search! [1] https://js.wiki/ https://js.wiki/

block_dagger 5y ago

I’ve been using Gollum on my local machine for personal wikis and it’s great!

pkulak 5y ago

This was a fun weekend project. Thanks! I will say, however, that getting it running took minutes; getting auth running was nearly a full day. Just HTTP Basic auth had me writing Ruby, then giving up and using a library that hasn't seen a single commit in years.

ptman 5y ago

Is there anything other than ikiwiki which works as a "wiki compiler" producing static html?