5 ms·

Raneto: Markdown-powered knowledge base for Node.js

62 points by gilbitron 12y ago

Mitranim 12y ago
Just what my colleague needed for our small KB redesign. Thanks for discovering!
- jbverschoor 12y ago
  Yep.. Was also looking for a markdown kb. Pref. with flat files
erlend_sh 12y ago
Cool! I've been hoping to see more wiki/knowledgebase type static site generators. I will admit that I fear for its longevity though. Any particular reason why you decided against building on top of something like assemble.io or wintersmith.io? Probably would have gotten a lot of functionality for free.
- gilbitron 12y ago
  I did consider simply building a KB with other static site generators, but I wanted something specifically designed for Knowledgebases and easy to setup and use.
antjanus 12y ago
Really cool stuff! I actually wrote a [flat-file CMS](https://github.com/AntJanus/popstar-cms https://github.com/AntJanus/popstar-cms) in Node as well, wasn't disappointed to see that my code and Raneto's code bares a good deal of similarities!
- gilbitron 12y ago
  Thanks. I actually created a flat-file CMS in PHP called Pico (http://picocms.org http://picocms.org) so I built on some of the lessons I learned creating Pico when building Raneto.
  - antjanus 12y ago
    I'm looking through it, I'm impressed by your plugins. I'm hoping to introduce that kind of structure into my application (hooks for remote posting, etc.). But gotta add one piece of functionality at a time! I haven't looked through your code completely so let me ask you something, what kind of an object do you pass to your templates? Do you pass the entire tree of information (all contents parsed as a JS object), or do you pass the current + children + parent? I'm just wondering. What I'm currently doing is sending the top-level content, current page, and children along with all of their information.
bckmn 12y ago
It would be nice to have some sort of security option around accessing the KB. Does anyone know of something like this with a login system?
- gilbitron 12y ago
  Raneto is secure because it doesn't have any kind of interface that can be hacked (e.g. a login page). To make changes to Raneto content you need to have access to your server file system.
  - throwaway5752 12y ago
    I believe he's not talking about authentication, he's talking about access/authorization.
  - nsfmc 12y ago
    i think the question was asking for most of the content publicly accessible but some of the content hidden behind a login. google sites does something like that but i haven't seen any flat-file cms'es that offer it.
imjared 12y ago
Well, that was easy. Went ahead and took our long-standing WIP wiki which was already markdown and threw it in here. We've been meaning to do something like this for a while, you just did it. Agreed with the point about security. We have a public part we want to make into a general KB but also a private part for internal. If anyone comes up with something, I'd love to see it. Lastly, because what comment wouldn't be complete without some sort of "criticism" on someone else's awesome, hard work, what prompted the decision to use the /* */ commenting for page-specific config? In my experience (maybe this is just because I've used jekyll too much) it seems that Yaml frontmatter is pretty typical for .md file config.
- mikegioia 12y ago
  For security, you could move this app behind an nginx proxy and handle auth (to say /admin/) via client SSL certificates. We do this for a number of internal applications that are exposed on the public web.
- gilbitron 12y ago
  Thanks. To be honest I just used a /* */ comment block because it was simple, but I'll have a look at implementing YAML.
  - NaNaN 12y ago
    How about gray-matter[1]? It supports YAML, TOML, JSON and Coffee. It can also auto-detect the type of front-matter. [1] https://github.com/assemble/gray-matter#lang https://github.com/assemble/gray-matter#lang
iaskwhy 12y ago
Sort of related: how do people handle images when using markdown documents for local/offline storage?
- NaNaN 12y ago
  I just put it in a specific directory, like root/data/images
Vaskivo 12y ago
Why the need for Node.js? Couldn't this simply be a static site? (I know there are tons of these, but most are "blog oriented)
- gilbitron 12y ago
  You could just create a static HTML site yes, but getting it generated for you from Markdown files is super handy. To generate it on the fly it needs to be powered by some kind of server (e.g. Node, PHP, Python etc). Nodejs was just a good choice of platform for this kind of thing.
NaNaN 12y ago
Good work. :) But without the cross reference module, it is just like a simple blog system.
- gilbitron 12y ago
  It could easily be "hacked" into a blog if you wanted to do that. At its core it is just a static site generator.
  - NaNaN 12y ago
    No, I don't need another static blog. I mean (bi-directional) cross reference is very important for memorization and even better than a simple search engine. Maybe you can use Disqus comment box to get related article but that's not good enough.
resu_nimda 12y ago
I had almost this exact idea recently, because I really wanted a minimal KB/wiki that I could edit in my text editor and collaborate on with others. It's encouraging to know that others feel the same way. You may have a competitor in a short while ;)
- zz1 12y ago
  Please, let us know!
abeiz 12y ago
Any plans to integrate API blueprints?
johnchristopher 12y ago
I have a question: what is the typical workflow for a user to "update" a markdown file on a static site that generates html ? I'm okay with ftp being so 90's but I don't see regular joes git-pushing their website.
wise_young_man 12y ago
Do you still have to style the knowledge base to match your site's design or use a layout? We've been working on a hosted knowledge base that you drop on a page and it inherits the design you already have. Our editor supports both WYSIWYG and Markdown too. Looking to see if people are interested and get feedback. http://userdeck.com/guides http://userdeck.com/guides
T-A 12y ago
Doesn't seem to work on Windows. Links resolve to http://localhost:3000/C:/Users/.. http://localhost:3000/C:/Users/... i.e. full path to content directory.
pros22su 12y ago
Looks very nice
ivan_ah 12y ago
Nice work! Is there any difference between a knowledge base and a wiki? And while on the topic of wikis, I wanted to plug dokuwiki which is an awesome feature-rich flat file wiki. I've been managing a lot of my writing as .txt files, even the ones with lots of math blocks---thank you MathJax! Also, the docutexit plugin allows me to export as .tex.
- gilbitron 12y ago
  I suppose the difference between Raneto and a "wiki" is that Raneto doesn't have all the multi-author features and collaboration that a wiki offers.
rpdillon 12y ago
I played around with this last night. Woke up this morning, visited raneto.com again, noticed that the website claims that for "commercial" projects, it requires a per-domain license. Except the source code on Github is licensed under MIT. I'm not sure how to reconcile those two things. http://docs.raneto.com/commercial-licensing http://docs.raneto.com/commercial-licensing
- sbussard 12y ago
  I noticed that too! Why don't they sell it as a service instead of trying to sell open source code?? Anyone who knows enough to use it knows enough to make it themselves
nemothekid 12y ago
The licensing is confusing. The GitHub project is released under MIT, but the site says you need to have a commercial license to use the software?
- chanux 12y ago
  The paid license is for commercial products. But that's still confusing. Raneto may be used in commercial projects with the one-time purchase of a commercial license.
  - nemothekid 12y ago
    It just seems that the commercial license is incompatible with the MIT license. With the MIT license there is nothing stopping someone from using it in a commercial product, the MIT license doesn't have that restriction. Even more confusing is if someone were to fork the project, would a user of that fork need to pay Raneto to use it a commercial license?

62 points by gilbitron 12y ago

Mitranim 12y ago

Just what my colleague needed for our small KB redesign. Thanks for discovering!

jbverschoor 12y ago
Yep.. Was also looking for a markdown kb. Pref. with flat files

erlend_sh 12y ago

Cool! I've been hoping to see more wiki/knowledgebase type static site generators. I will admit that I fear for its longevity though. Any particular reason why you decided against building on top of something like assemble.io or wintersmith.io? Probably would have gotten a lot of functionality for free.

gilbitron 12y ago
I did consider simply building a KB with other static site generators, but I wanted something specifically designed for Knowledgebases and easy to setup and use.

antjanus 12y ago

Really cool stuff! I actually wrote a [flat-file CMS](https://github.com/AntJanus/popstar-cms https://github.com/AntJanus/popstar-cms) in Node as well, wasn't disappointed to see that my code and Raneto's code bares a good deal of similarities!

gilbitron 12y ago
Thanks. I actually created a flat-file CMS in PHP called Pico (http://picocms.org http://picocms.org) so I built on some of the lessons I learned creating Pico when building Raneto.
- antjanus 12y ago
  I'm looking through it, I'm impressed by your plugins. I'm hoping to introduce that kind of structure into my application (hooks for remote posting, etc.). But gotta add one piece of functionality at a time! I haven't looked through your code completely so let me ask you something, what kind of an object do you pass to your templates? Do you pass the entire tree of information (all contents parsed as a JS object), or do you pass the current + children + parent? I'm just wondering. What I'm currently doing is sending the top-level content, current page, and children along with all of their information.

bckmn 12y ago

It would be nice to have some sort of security option around accessing the KB. Does anyone know of something like this with a login system?

gilbitron 12y ago
Raneto is secure because it doesn't have any kind of interface that can be hacked (e.g. a login page). To make changes to Raneto content you need to have access to your server file system.
- throwaway5752 12y ago
  I believe he's not talking about authentication, he's talking about access/authorization.
- nsfmc 12y ago
  i think the question was asking for most of the content publicly accessible but some of the content hidden behind a login. google sites does something like that but i haven't seen any flat-file cms'es that offer it.

imjared 12y ago

Well, that was easy. Went ahead and took our long-standing WIP wiki which was already markdown and threw it in here. We've been meaning to do something like this for a while, you just did it. Agreed with the point about security. We have a public part we want to make into a general KB but also a private part for internal. If anyone comes up with something, I'd love to see it. Lastly, because what comment wouldn't be complete without some sort of "criticism" on someone else's awesome, hard work, what prompted the decision to use the /* */ commenting for page-specific config? In my experience (maybe this is just because I've used jekyll too much) it seems that Yaml frontmatter is pretty typical for .md file config.

mikegioia 12y ago
For security, you could move this app behind an nginx proxy and handle auth (to say /admin/) via client SSL certificates. We do this for a number of internal applications that are exposed on the public web.
gilbitron 12y ago
Thanks. To be honest I just used a /* */ comment block because it was simple, but I'll have a look at implementing YAML.
- NaNaN 12y ago
  How about gray-matter[1]? It supports YAML, TOML, JSON and Coffee. It can also auto-detect the type of front-matter. [1] https://github.com/assemble/gray-matter#lang https://github.com/assemble/gray-matter#lang

iaskwhy 12y ago

Sort of related: how do people handle images when using markdown documents for local/offline storage?

NaNaN 12y ago
I just put it in a specific directory, like root/data/images

Vaskivo 12y ago

Why the need for Node.js? Couldn't this simply be a static site? (I know there are tons of these, but most are "blog oriented)

gilbitron 12y ago
You could just create a static HTML site yes, but getting it generated for you from Markdown files is super handy. To generate it on the fly it needs to be powered by some kind of server (e.g. Node, PHP, Python etc). Nodejs was just a good choice of platform for this kind of thing.

NaNaN 12y ago

Good work. :) But without the cross reference module, it is just like a simple blog system.

gilbitron 12y ago
It could easily be "hacked" into a blog if you wanted to do that. At its core it is just a static site generator.
- NaNaN 12y ago
  No, I don't need another static blog. I mean (bi-directional) cross reference is very important for memorization and even better than a simple search engine. Maybe you can use Disqus comment box to get related article but that's not good enough.

resu_nimda 12y ago

I had almost this exact idea recently, because I really wanted a minimal KB/wiki that I could edit in my text editor and collaborate on with others. It's encouraging to know that others feel the same way. You may have a competitor in a short while ;)

zz1 12y ago
Please, let us know!

abeiz 12y ago

Any plans to integrate API blueprints?

johnchristopher 12y ago

I have a question: what is the typical workflow for a user to "update" a markdown file on a static site that generates html ? I'm okay with ftp being so 90's but I don't see regular joes git-pushing their website.

wise_young_man 12y ago

Do you still have to style the knowledge base to match your site's design or use a layout? We've been working on a hosted knowledge base that you drop on a page and it inherits the design you already have. Our editor supports both WYSIWYG and Markdown too. Looking to see if people are interested and get feedback. http://userdeck.com/guides http://userdeck.com/guides

T-A 12y ago

Doesn't seem to work on Windows. Links resolve to http://localhost:3000/C:/Users/.. http://localhost:3000/C:/Users/... i.e. full path to content directory.

pros22su 12y ago

Looks very nice

ivan_ah 12y ago

Nice work! Is there any difference between a knowledge base and a wiki? And while on the topic of wikis, I wanted to plug dokuwiki which is an awesome feature-rich flat file wiki. I've been managing a lot of my writing as .txt files, even the ones with lots of math blocks---thank you MathJax! Also, the docutexit plugin allows me to export as .tex.

gilbitron 12y ago
I suppose the difference between Raneto and a "wiki" is that Raneto doesn't have all the multi-author features and collaboration that a wiki offers.

rpdillon 12y ago

I played around with this last night. Woke up this morning, visited raneto.com again, noticed that the website claims that for "commercial" projects, it requires a per-domain license. Except the source code on Github is licensed under MIT. I'm not sure how to reconcile those two things. http://docs.raneto.com/commercial-licensing http://docs.raneto.com/commercial-licensing

sbussard 12y ago
I noticed that too! Why don't they sell it as a service instead of trying to sell open source code?? Anyone who knows enough to use it knows enough to make it themselves

nemothekid 12y ago

The licensing is confusing. The GitHub project is released under MIT, but the site says you need to have a commercial license to use the software?

chanux 12y ago
The paid license is for commercial products. But that's still confusing. Raneto may be used in commercial projects with the one-time purchase of a commercial license.
- nemothekid 12y ago
  It just seems that the commercial license is incompatible with the MIT license. With the MIT license there is nothing stopping someone from using it in a commercial product, the MIT license doesn't have that restriction. Even more confusing is if someone were to fork the project, would a user of that fork need to pay Raneto to use it a commercial license?