My favorite for now stays mkdocs (http://www.mkdocs.org/). For relative small ones with the material theme (http://squidfunk.github.io/mkdocs-material/) and bigger ones (because of top bar) with bootswatch theme (http://mkdocs.github.io/mkdocs-bootswatch/). It works the same, just builds a site from your MD files but creates a static site which can be hosted anywhere (e.g. github/gitlab pages via auto CI). Editing and creating your own theme is also easy and documented.
Installation is easiest I found for docs sites (pip install mkdocs) and it's blazingly fast. Comes with good themes and proper responsive design (saw some issues in Raneto on my ios). Has proper live reloading and build in serve functionality.
For large projects (enterprise size) we have made our own version based on what I learned from the Polymer docs (https://github.com/Polymer/doc) but removed the GAE requirement. Also, we are considering if using SO Enterprise is a good solution. Personally I'm in favor for in house docs and knowledge sharing for that. It's so flexible and people are already used to it. But that is a different ball park considering the OP.
To end with a positive note. Raneto seems to support much of the same as mkdocs or any of its alternatives. It looks good and whilst static site is something I want I understand it is not a deal breaker for all. In addition, Raneto mentions authentication is built in which is a nice thing if I want to host for internal stuff on a public domain so external customers can also use it without requiring a VPN account. Overall, nice work! Not for today, but I have bookmarked it.
Looks great! One thing that would be nice would be the ability for Raneto to act as a static Docs generator. Looks like you have to use nodejs as the server as it stands. I'd like to be able to use a simple static http-server.
It looks like something that could be handled just as well using Heckle by Marijn Haverbeke. It reads content and layouts from a Jekyll-like directory structure. Naturally, it uses CodeMirror for syntax highlighting.
There are loads of options for static site generators (here[0] is a good list of ~200), but it doesn't solve all problems. One question, for example, is how to get search functionality.
What works for me with Hugo (because I'm already using these tools all day anyway) is to keep the site in a Github repository.
Then when I make a change it triggers TravisCI to do a full site rebuild. (Takes longer to install Hugo than to actually run it)
Then once it's built, Travis has built in support for uploading to S3, and away we go.
Doesn't work for everyone, but it's really smooth and simple for me, I can even just go to Github, create a new page, and save it right there from the site. Which means I can edit from any device I want.
I wonder what makes this a _knowledge base_ as opposed to a flat file CMS?
A few months ago I left Evernote for my own implementation because I felt that Evernote gave me too little expressive power: No hierarchy, no typed relationships, no plugins. Basically, I was looking for a combination of outliner and concept map, combined with easy image handling. Plus, I wanted to easily add _applications_ like an ebook library, journaling, timelines of events, and generation of static websites and presentations.
I am a huge fan of simplicity and even toyed with PicoCMS by the same author as Raneto. Ultimately though, at least for me, a combination of a simple mysql database with markdown as content format gave me the power I wanted for my personal knowledge base, https://knowfox.com
The term has a long history - as the Wikipedia page [0] points out, "knowledge base" was used to distinguish systems that could actively reason about data using rules (and a rules-engine to run them) -- e.g. expert systems -- from databases, where the data just sits there. However, these days, it's used differently:
From the Wikipedia page[0]:
Knowledge management products adopted the term "knowledge-base" to describe their repositories but the meaning had a subtle difference. In the case of previous knowledge-based systems the knowledge was primarily for the use of an automated system, to reason about and draw conclusions about the world. With knowledge management products the knowledge was primarily meant for humans, for example to serve as a repository of manuals, procedures, policies, best practices, reusable designs and code, etc. Of course in both cases the distinctions between the uses and kinds of systems were ill defined. As the technology scaled up it was rare to find a system that could really be cleanly classified as knowledge-based in the sense of an expert system that performed automated reasoning and knowledge-based in the sense of knowledge management that provided knowledge in the form of documents and media that could be leveraged by humans
I've been starting to suffer from Markdown fatigue and investigating tools that support RST or asciidoc. I wonder if this system might support those tools in the future?
I admit, I haven't tried to write a lot of RST or asciidoc beyond playing around with it. And it's a good point -- docs that are hard to write don't get written.
Having used a lot of markdown and reStructuredText, I can see the arguments that the lack of common standards in markdown is a huge pain. There's still a lot of variety between markdown implementations and while Common Mark and open GFM standards are helping to a point, you still can't always count on a markdown engine to have things as basic as definition list support or HTML anchor support (linkable ids for sub-headings), and there are still some weird subtle implementation differences in those things.
There's also a lot to be said about the way that reStructuredText provides standard plugin spaces in the markup. While it may look over verbose at first glance, it is a great thing when you start to pick up that a lot of reStructuredText is based on the same plugin markup and there's a consistent way to work with new plugins. Something like that could be hugely useful to Markdown, and probably could have stymied some of the complications in standardizing things like Common Mark and GFM had that consideration been baked in from early on.
Most of Markdown is great for me and feels natural. Headings, bold, italics, lists -- those are all great.
Examples that don't feel natural are image syntax, dropping down to HTML for unsupported features (pre-supposes output format), emphasis on presentation vs. semantics, the various flavors of writing tables, etc. How do I write an index? A table of contents? Any way to differentiate a footnote or an aside from a basic link?
YAML front matter is a great ad hoc standard for including metadata about a document within the document. It would be great if the various flavors of Markdown standardized on that, too.
I've started work on an evolved markdown version called text with instructions (.texti) [1]. Anyways, what's broken in markdown? The image links are ugly e.g. . Why not {{pic.gif}}? Almost everybody incl. Wikipedia markup is using = for headings e.g. =Heading 1=. Why not also in Markdown? Another good reason is that # is the "universal" comment marker in the unix world. If you mix and match yaml front matter / back matter (meta data) with comments - why not use the same comments? Did you know - there are no comments in markdown. And so on and so on. It's time to fix (evolve) markdown. Cheers.
I wonder also, gitbook-cli supports both md and adoc. Asciidoctor is easier to write and you don't have to use its advanced features for it to become superior to Markdown.
> so you can just prefix every item with `1` if you'd like.
oh, didn't knew that, use asterisks instead of dots is for bulletspoints in asciidoc. For unordered lists use more than one asterisk (HN breaks my example here), look at this example http://www.methods.co.nz/asciidoc/chunked/ch17.html if you mean Implicit numbering
It is a much heavier setup and wikis have been out of favor past years. As of such their theming and configuration is not up to par when compared to the new kids on the block. In my company (multinational) even IT is phasing out its support, which usually means it's really dying ;).
Your app gobbled up all available RAM and caused my laptop to slow to a crawl. I had to switch virtual terminals to kill the tab responsible for your site.
Nice! The CSV format for code blocks grabbed my attention. That's possibly friendlier to write by hand than tables (https://github.com/adam-p/markdown-here/wiki/Markdown-Cheats...) and also nice because you could make your table in something like Excel/Libre, save to csv and then copy/paste.
For people who value full control and self hosting, Raneto looks like a good starting point to build from.
After having had to build knowledge bases in each company I worked in or go through the pain of implementing something bloated like Zendesk, I built a SaaS version of what I really wanted: the simplest knowledge base out there that stays out of your way.
</a>](http://foo.com"></a>){kind=link}
Installation is easiest I found for docs sites (pip install mkdocs) and it's blazingly fast. Comes with good themes and proper responsive design (saw some issues in Raneto on my ios). Has proper live reloading and build in serve functionality.
For large projects (enterprise size) we have made our own version based on what I learned from the Polymer docs (https://github.com/Polymer/doc) but removed the GAE requirement. Also, we are considering if using SO Enterprise is a good solution. Personally I'm in favor for in house docs and knowledge sharing for that. It's so flexible and people are already used to it. But that is a different ball park considering the OP.
To end with a positive note. Raneto seems to support much of the same as mkdocs or any of its alternatives. It looks good and whilst static site is something I want I understand it is not a deal breaker for all. In addition, Raneto mentions authentication is built in which is a nice thing if I want to host for internal stuff on a public domain so external customers can also use it without requiring a VPN account. Overall, nice work! Not for today, but I have bookmarked it.