7 ms·

Raneto – Markdown Knowledgebase Platform

183 points by iamdeedubs 9y ago

drew-y 9y ago
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.
- adammenges 9y ago
  Yeah that be a great addition
- aizatto 9y ago
  I've been using Phenomic https://phenomic.io https://phenomic.io for my personal site https://www.aizatto.com https://www.aizatto.com
  - carussell 9y ago
    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 http://marijnhaverbeke.nl/blog/heckle.html
  - michaelmior 9y ago
    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/ https://www.staticgen.com/
- rfrank 9y ago
  Hugo with a theme like docdock is pretty neat (http://gohugo.io/ http://gohugo.io/ & http://docdock.netlify.com/ http://docdock.netlify.com/)
  - bedros 9y ago
    how would you add a new post (for a blog) edit a file, and upload it to the site?
    - reificator 9y ago
      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.
    - bdot 9y ago
      Netlify CMS can be a good choice if you are looking for admin section, it nicely integrates with GitHub.
mcone 9y ago
Previous discussion: https://news.ycombinator.com/item?id=7832991 https://news.ycombinator.com/item?id=7832991
EddieRingle 9y ago
Why something like this instead of—for instance—a wiki?
- patrickdavey 9y ago
  Yup, was thinking the same. Vimwiki in markdown format and can render the entire wiki to html.
- FutureSpec 9y ago
  A wiki would require a backing database and server process (I think). This platform is flat files.
  - Spivak 9y ago
    Dokuwiki is flat files only.
  - toomim 9y ago
    This requires a server process.
- bastijn 9y ago
  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 ;).
drhayes9 9y ago
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?
- pspeter3 9y ago
  Any reasons for the markdown fatigue?
  - geraldbauer 9y ago
    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 https://texti.github.io
  - drhayes9 9y ago
    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.
  - WorldMaker 9y ago
    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.
bastijn 9y ago
My favorite for now stays mkdocs (http://www.mkdocs.org/ http://www.mkdocs.org/). For relative small ones with the material theme (http://squidfunk.github.io/mkdocs-material/ http://squidfunk.github.io/mkdocs-material/) and bigger ones (because of top bar) with bootswatch theme (http://mkdocs.github.io/mkdocs-bootswatch/ 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 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.
- squidfunk 9y ago
  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/#tabs http://squidfunk.github.io/mkdocs-material/getting-started/#...
  - bastijn 9y ago
    Great! Thanks for letting me know. You made a great theme.
olav 9y ago
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 https://knowfox.com
- dgfgfdagasdfgfa 9y ago
  > knowledge base I just figured this was a new term for a searchable FAQ. What do you think the difference is?
  - deleted 9y ago
    [deleted]
  - qohen 9y ago
    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 https://en.wikipedia.org/wiki/Knowledge_base
helpsite 9y ago
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/ https://HelpSite.io/ Don't have Markdown support (yet) but we have a generous Free tier including custom domain (CNAME) support.
ivanceras 9y ago
Shameless plug, I'm working on Github flavored Markdown editor with graphing plugin[0] [0]: http://ivanceras.github.io/spongedown-editor/ http://ivanceras.github.io/spongedown-editor/
- nullify88 9y ago
  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.
- staticvar 9y ago
  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-Cheatsheet#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.
igravious 9y ago
What makes this a knowledge-base rather than a lightweight CMS?
staticvar 9y ago
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 http://mdwiki.info echo "# Hello World" > index.md python -m SimpleHTTPServer 8000 ``` Now visit http://localhost:8000 http://localhost:8000 in your browser and it's live. Publish to Github Pages and you're golden.

183 points by iamdeedubs 9y ago

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.

adammenges 9y ago
Yeah that be a great addition
aizatto 9y ago
I've been using Phenomic https://phenomic.io https://phenomic.io for my personal site https://www.aizatto.com https://www.aizatto.com
- carussell 9y ago
  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 http://marijnhaverbeke.nl/blog/heckle.html
- michaelmior 9y ago
  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/ https://www.staticgen.com/
rfrank 9y ago
Hugo with a theme like docdock is pretty neat (http://gohugo.io/ http://gohugo.io/ & http://docdock.netlify.com/ http://docdock.netlify.com/)
- bedros 9y ago
  how would you add a new post (for a blog) edit a file, and upload it to the site?
  - reificator 9y ago
    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.
  - bdot 9y ago
    Netlify CMS can be a good choice if you are looking for admin section, it nicely integrates with GitHub.

mcone 9y ago

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

EddieRingle 9y ago

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

patrickdavey 9y ago
Yup, was thinking the same. Vimwiki in markdown format and can render the entire wiki to html.
FutureSpec 9y ago
A wiki would require a backing database and server process (I think). This platform is flat files.
- Spivak 9y ago
  Dokuwiki is flat files only.
- toomim 9y ago
  This requires a server process.
bastijn 9y ago
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 ;).

drhayes9 9y ago

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?

pspeter3 9y ago
Any reasons for the markdown fatigue?
- geraldbauer 9y ago
  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 https://texti.github.io
- drhayes9 9y ago
  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.
- WorldMaker 9y ago
  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.

bastijn 9y ago

My favorite for now stays mkdocs (http://www.mkdocs.org/ http://www.mkdocs.org/). For relative small ones with the material theme (http://squidfunk.github.io/mkdocs-material/ http://squidfunk.github.io/mkdocs-material/) and bigger ones (because of top bar) with bootswatch theme (http://mkdocs.github.io/mkdocs-bootswatch/ 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 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.

squidfunk 9y ago
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/#tabs http://squidfunk.github.io/mkdocs-material/getting-started/#...
- bastijn 9y ago
  Great! Thanks for letting me know. You made a great theme.

olav 9y ago

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 https://knowfox.com

dgfgfdagasdfgfa 9y ago
> knowledge base I just figured this was a new term for a searchable FAQ. What do you think the difference is?
- deleted 9y ago
  [deleted]
- qohen 9y ago
  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 https://en.wikipedia.org/wiki/Knowledge_base

helpsite 9y ago

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/ https://HelpSite.io/ Don't have Markdown support (yet) but we have a generous Free tier including custom domain (CNAME) support.

ivanceras 9y ago

Shameless plug, I'm working on Github flavored Markdown editor with graphing plugin[0] [0]: http://ivanceras.github.io/spongedown-editor/ http://ivanceras.github.io/spongedown-editor/

nullify88 9y ago
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.
staticvar 9y ago
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-Cheatsheet#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.

igravious 9y ago

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

staticvar 9y ago

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 http://mdwiki.info echo "# Hello World" > index.md python -m SimpleHTTPServer 8000 ``` Now visit http://localhost:8000 http://localhost:8000 in your browser and it's live. Publish to Github Pages and you're golden.