Raneto – Markdown Knowledgebase Platform | Hacker News Reader

Raneto – Markdown Knowledgebase Platform

raneto.com

183 pointsiamdeedubs41 comments

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.

I'm the author of the Material theme which actually has a top bar, a feature called tabs, see http://squidfunk.github.io/mkdocs-material/getting-started/#...

Great! Thanks for letting me know. You made a great theme.

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.

Yeah that be a great addition

I've been using Phenomic https://phenomic.io for my personal site https://www.aizatto.com

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.

http://marijnhaverbeke.nl/blog/heckle.html

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.

[0] https://www.staticgen.com/

Hugo with a theme like docdock is pretty neat (http://gohugo.io/ & http://docdock.netlify.com/)

how would you add a new post (for a blog) edit a file, and upload it to the site?

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.

Netlify CMS can be a good choice if you are looking for admin section, it nicely integrates with GitHub.

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

> knowledge base

I just figured this was a new term for a searchable FAQ. What do you think the difference is?

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

[0] https://en.wikipedia.org/wiki/Knowledge_base

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?

Any reasons for the markdown fatigue?

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. ![](fail.gif). 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.

[1] More at -> https://texti.github.io

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.

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.

You could use Pelican (getpelican.com) -- it's an SSG that supports Markdown and RST and asciidoc and is generally extensible.

Pelican is great for blogs. I don't know that I'd suggest it for a "Knowledgebase".

The readthedocs engine is RST friendly. Personally I prefer documentation that's easy to write and RST is not that.

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.

Asciidoctor has a plugin for Jekyll you might be interested in: https://github.com/asciidoctor/jekyll-asciidoc

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.

== What is easier to write?

// adoc comment

== What is easier to write?

image:adoc-foo.jpg[link="http://foo.com"]

== What is easier to write?

1. first md - no auto numbering

2. second md - no auto numbering

3. third md - no auto numbering

. first adoc - auto numbering

. second adoc - auto numbering

. third adoc - auto numbering

What is easier to write?

[Get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/my-md-file.pdf)

link:{ctx_path}/assets/my-adoc-file.pdf[Get the PDF]

> . first adoc - auto numbering

That looks like a bullet to me. How do you differentiate unordered and ordered lists?

Also, markdown auto-numbers too, so you can just prefix every item with `1` if you'd like.

> 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

You could also do:

[start=5]

. nr-5

. nr-6

. nr-7

Previous discussion: https://news.ycombinator.com/item?id=7832991

I love markdown! A similar project but without the need for a custom buildchain or serverside software is MDwiki.

```

mkdir my-site

cd my-site

curl http://mdwiki.info

echo "# Hello World" > index.md

python -m SimpleHTTPServer 8000

```

Now visit http://localhost:8000 in your browser and it's live. Publish to Github Pages and you're golden.

Why something like this instead of—for instance—a wiki?

Yup, was thinking the same. Vimwiki in markdown format and can render the entire wiki to html.

A wiki would require a backing database and server process (I think). This platform is flat files.

Dokuwiki is flat files only.

This requires a server process.

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

Shameless plug, I'm working on Github flavored Markdown editor with graphing plugin[0]

[0]: http://ivanceras.github.io/spongedown-editor/

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.

I'm running Chrome 59.0.3071.115. Fedora 26 64bit.

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.

What makes this a knowledge-base rather than a lightweight CMS?

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.

https://HelpSite.io/

Don't have Markdown support (yet) but we have a generous Free tier including custom domain (CNAME) support.

Reply on news.ycombinator.com