ryanlelek/raneto

Markdown powered Knowledgebase Wiki for Node.js

Raneto

Raneto is a free, open, simple Markdown powered knowledge base for Node.js. Find out more →

Important Updates

• Please ensure you're on Raneto v0.17.1 for the latest security fixes
• Join the Roadmap Discussion

Demo and Documentation

Visit https://docs.raneto.com to see a demo.

Quickstart

Visit the Example Repo
See the installation guide for more information.

Docker / Containers

Official Raneto container images on Docker Hub

Run the default container, and access on localhost:3000
docker run --rm -it --publish 3000:3000 raneto/raneto:latest

Same as above, but provide your own content and configuration

docker run --rm -it --publish 3000:3000 \
  --volume \
  --volume \
  raneto/raneto:latest

Want to poke around the files in the container? Get a shell:
docker run --rm -it --publish 3000:3000 --volume raneto/raneto:latest /bin/sh

Security

Make sure you edit the default username and password in your config.js file.

##### WARNING #####
// You MUST change the username and password for security
// Do NOT use "admin" as a username as it's easily guessed.
// You are encouraged to use tools to generate a password
// Preferably, use a local password manager
// If you absolutely must use an online tool, here are some suggestions
// https://bitwarden.com/password-generator/
// https://www.grc.com/passwords.htm

Markdown Reference

If you want to embed links and images, you'll need to use the Markdown syntax.
See this Markdown Guide

Links

• Configuration
• Production Notes
• Deploying to Heroku
• Contributing

Showcase

Are you using Raneto in the wild? We'd love to see it. Please add it to this list:

• Raneto Docs

Related Projects

• Default Theme
• Deploy Raneto to your servers with Ansible by @ryanlelek
• Run Raneto in a Vagrant container by @draptik
• Deploy Raneto using Docker container by @madhuakula

Credits

• Raneto was created by Gilbert Pellegrom
• Maintained by Ryan Lelek from AnsibleTutorials.com
• Logo by @mmamrila
• Released under the MIT license

raneto's Issues

Loading Raneto with Forever doesn't work.

So trying to keep Raneto running using Forever isn't working. I'll try to fix it and post the results here.

Provide a way to automatically create a page's TOC

It would be really nice to have a way (a variable?) to create the TOC of the page that is being edited. Something like what Wikipedia provides.

Multi site support

Would you consider making an update to allow support for multiple sites? We have groups of applications which are in need of KB system but we want it centralized. Is that possible today?

Implement a file for listing the order

Rather than using a sort key it'd be much simpler if each directory contained a toc file, where you'd list the name of the file and it'd order based on that.

At the moment if I want to move a page, I've got to go through and re-order every file's sort key, which is painstakingly boring.

Access config variables from markdown files?

Is it possible to access the config variables from the markdown files themselves? I added a line to the renato.js file to replace a content variable but wanted to know if there is an easier way? Thanks.

How to show '{{last_modified}}' variable on home.html

I want to append last modified time to the '{{title}}' variable, how should I do?

Password protection

Is it possible to use some kind of password protection on Raneto? For example something like htaccess what you have on Apache?

Dynamic categories using hashtags

Recognize 'Tags:' in the comment header and list these tags as categories on the main knowledgebase page; allows md files to appear in multiple relevant categories without duplicating content.

Documentation Request: Updating to New Releases

Hello,

I think it is pretty important to write up some documentation about the author/org recommended method of updating from release to release. Right now, it looks like the user would have to grab a new release and move the content folder - is that accurate?

Just curious what your intended methodology for updating will be and if there could be a section laid out to describe it,

Thanks

Config local and prod domains

Hello,

I do not understand how to configure a domain normal places of localhost: 3000 that either locally or on my server. Heroku is still not mandatory?

How to do this please?

Thank you.

Link to category url to first file url, rather than 404.

If I have a category called "posts" and the first file in that is "my-first-post",

Set it up so that if I try to access /posts it redirects me to /posts/my-first-post, tather than a 404 page.

Add masonry to homepage layout

Add a masonry type layout to homepage so that there isn't huge gaps between rows of categories.

Basic Auth Guide / Password Feature

Is there a way of getting Basic Auth working with Raneto? I am really struggling, but I am new to node.js.

Add category "archives"

Show an "archive" when visiting a folder root. Possibly allow override with index.md as with homepage.

Make content folder public by default

Markdown are document, not source files.

I think the content/ could be stored under public/ (just as a default for #20). This way it makes more sense to store images under content/ as well (as I proposed on #9).

I'm still not familiar on how Express.js handle the public/ folder, but may be easy to serve files directly unless *.md (like an Apache mod_rewrite could do).

add multilevel catalogue show in main page

add multilevel catalogue show in main page, reflect hierarchy

Feature: Embedded MarkDown editor

Hi guys,

Firstly, great repo!
Especially for people who are relatively new to web development or javascript and frameworks, or markdown for that matter, who can use this as something of a simple boilerplate to really get into improving and extending the existing features, i.e. very good hands-on learning experience!

But I was wondering if it's on the roadmap to integrate an embedded editor, of which there are a few here on Github as well?
It seems an obvious next step for a near future release.

Any plans?

Option to base page title on filename instead of comment block

I would love to have the option of getting the page title from the filename instead of having to specify a comment block.

We use several tools to work with Markdown, like Markdownpad and Pandoc, and the comment block is rendered by them as standard text. This is because basic Markdown doesn't support comment blocks.

Why sync ?

After looking at the code of raneto-core I can see that you are using sync io. Isn't that slow and opposite of the node practices.

Can't search in Chinese.

I find that it can't work with Chinese. :(

Транслит в URL

Если название файлов и папок делать на русском, то в урл будет кириллица. Файлы ладно - можно и в латинице делать, так как в файле есть title, но как сделать папки на английском, но чтобы в URL было на латинице?

Themes

Swap out the views folder for a themes folder and add a "theme" options to config to allow setting the active theme.

If active theme folder doesn't exist then fallback to "default".

nodejs not node on Ubuntu Server

On an ubuntu server nodejs is accessed via the "nodejs" command, not the "node" command.

So the "npm start" command will break.

Having 'content' directory configurable

Making content directory configurable helps to just point to the existing source content without copying stuffs around. By default it should work the way it is now.

If you like this feature then I can send you a pull request for this...

Any plans to allow editing/creating pages from the browser?

This is really nice, but I think it would be much more powerful if there was a way to create/edit pages from the editor. Any plans for this?

Switch from bower to npm

As a developer I would like to remove the bower dependency so there will be fewer moving parts and things will be easier to keep track of.

Is there any way to set up cookie auth?

I tried to add a simple check on req.cookies that redirects if it fails to find a cookie. However, I'm experiencing strange errors about headers being sent when I try to call res.redirect() inside the main app.all().

Is there a preferred method of doing this?

License Confusion

I'm confused about the license of Raneto. You have an MIT license, but the website says "To use Raneto in commercial projects you must purchase a commercial license". How does this work in practice?

This Raneto doesn't support online creating pages, right?

does it support online creating pages or not?

and another issue is that how to add Chinese searching support?

above two.

thank u.

Demo running really slow

I don't know if it's just because you're experiencing high traffic right now or not, but your demo seems to be really sluggish at the moment with a 5.6s average waiting for a response from the server for each resource. Actual download times are ~1ms, but full page load takes over 13s. Is the demo server just under heavy load?

Add images support

Allow people to store images in public/images and add a %images_url% variable that can be used in Markdown files (like %base_url%).

Publish to npm

Firstly, just want to say how much I love this project, thanks for your great work :)

I see that raneto is published to npm. It actually runs very well like this. Great job exposing app and config!

However, it appears that it is not possible to configure the content directory, which makes it impractical to use it this way at the moment.

Is there any chance this could be fixed?

Thanks very much!

Implement YAML for meta instead of comment block

Add analytics config option

Add an option to config.js that would allow a {{config.analytics}} variable to be used in the template. Allow any HTML (including scripts). E.g. Google Analytics.

Feature request: Page series

I made a post on Jekyll Help already that pretty much explains it.

Would love to see a simple way to create a series of posts, linked together and set in a certain order that could be changed without editing each page individually.

hide sub-folder

Is it possible to hide a sub-folder (but still have links that go to it) from the main page? In the example below, I would want Categories 1, 2, and 3 to show up on the main page and be able to link to Sub-Category 2.a but hide Sub-Category 2.a from the TOC?

main content
    folder category 1
    folder category 2
        folder subcategory 2.a
    folder category 3

Allow ordering of pages and categories

This would involve several steps:

• In config.js have an option to switch between alphabetical (default) and numerical sorting (for pages and categories?)
• Pages could be sorted by adding a "Sort" meta value which takes an integer
• Categories could be sorted by prefixing folder names with {sort}_. For example 0_folder, 1_folder, 2_folder etc.
• Category prefixes would need to be ignored in slugs and titles

Incomplete document

Adding a way to mark a document as incomplete would be good. This would be useful if some documentation is available, but not all of it.

Prevent syntax highlighting

I am experiencing incorrect language detection by highlight.js.

Is there any config to prevent highlight.js in Raneto?

In highlight.js doc they suggest to use nohighlight class on code element. However Raneto generate lang-nohighlight on code element.

If Raneto could use Fenced code blocks of Markdown Extra or something similar I think I could achieve this with

    ```nohighlight
   code here
    ```

Feature Request for Missing but Necessary Features.

Some of the critical functions that I feel Raneto might need is as follows:

• Login page and user management.
• Upload and management of documents or some form of document editing from the website.
• Document history and archiving.
• HTTPS support activation from webpage.

Support subcategories

I'm interested in creating a knowledgeable with hundreds of pages where are subcategorized up to 6 levels deep.

I read in your docs that subcategories are always displayed as top level categories. Why is this? Is it possible to implement such subcategory feature?

Nginx proxy pass does not work

A nginx proxy pass such as the one below does not work.
All links go to my base domain instead of domain/site/file*.

location /site {
        proxy_pass    http://localhost:3000;
}

Urls generated with full file path on Windows

Probably related to running this on Windows, but when I run the application the links from the landing page are returning 404s. Here's an example of a generated url:

http://localhost:3000/D:/temp/Raneto-0.2.0/content/usage/configuration

When I manually remove "D:/temp/Raneto-0.2.0/content/" I see the correct page.

Provide option to specify category title manually, rather than automatically generated

This would be handy for custom capitalization and special characters, or just for having shorter URLs (e.g. /faqs/... instead of /frequently-asked-questions/... A simple method would probably be to include a title file in the category folder with the custom title (similar to the way categories are sorted).

Image URLS

I have left the standard config unchanged for the image location...
image_url: '/images',

I am running a windows server and Raneto is working perfectly but I just can't get embedded images to display. MD files display perfectly.

I have created an images folder in the root as I guess this is where the images should be?

Within this folder I have placed an image called image.jpg

If I create an image in an MD file like this....
![Test](%image_url%/image.jpg)

The image is not displayed. If I check the source html on the rendered web page I can see the url is ...
<img alt="Test" src="/images/image.jpg">

I can't figure out if this is wrong with the root image folder location or an issue with Raneto locating o them?

Help much appreciated on this one.

Add path to search result

when searching, you now get the title of the page and part of the page content as result, however if you use folders to categorize it could be useful to get the path to the file visualized with the search result.

this could be configurable with a flag.

usecase: create a folder for backend and 1 for frontend code. both need documentation about how multilanguage or logging or any other generic idea is being handled.
but you end up with 2 files called logging.md or worse, you have to add the category in the title again which is tedious ...

Grunt - Gulp for automation

I will be very interested in adding one of those to raneto. I got experience mostly with Grunt. Let me know if this could be interesting for you

Start from different project without requiring install

I would love to be able to run raneto by creating my content on my own git repo, configure my own package.json, do a npm install --save raneto and then add my own entry point similar to what you have on bin\www:

However, I would need to pass to app.js a config file to use (which I want stored on my own repo), and also be able to specify a static files configuration for express that is evaluated before ranetos own public/ folder.

For example, if app.js was something like:

var express = require('express'),
    path = require('path'),
...
module.exports = function(options) {
    options = options || {}
   // Setup views
  ...
  // Setup Express
 app.use(favicon(options.favicon || (__dirname +'/public/favicon.ico')));
 ...
 if (options.static) {
     app.use(express.static(options.static));
 }

 app.use(express.static(path.join(__dirname, 'public')));
 ...
 // Setup config
 extend(raneto.config, config, options.config || {});

Then in my own entry point could just do:

...
var app = require('../app')({ config: require("./config"), static: "override" });
app.set('port', process.env.PORT || 3000);
...

To provide an override folder for raneto resources, and a custom config.

What do you guys think? Does it make sense? Should I submit a PR? Or is there other way to do this?

The main goal are:

• Keep in my repo only what I authored, and no raneto code.
• Let people get my repo and just do a standard npm install; npm start to start up the site.

Markdown Extra

Would it be possible to make use of Markdown Extra? It gives some benefits over standard Markdown such as being able to add classes to images etc.

Highlight search term in search results

Could probably just be done using jQuery.