Lets start with a very common example where you own a product. Users are now facing difficulties accessing some or the other functionalities of your product and they keep on mailing in search of solutions. How good will it be if there exists a particular documentation or knowledge base which lists all of the product functionality and how to use it? That will be great isn’t it?? ;)
Generally knowledge base is a well organized repository for information about a particular subject.
Knowledge base increases the speed and ease with which a customer is able to find a solution to their problems. It should be organized and educational enough to solve common problems or common functionalities efficiently. Another advantageous factor of having a well organized knowledge base is that it can save lot of organization fund by decreasing the amount of time employees spend trying to find information regarding your particular product.
Here we are going to discuss about such a base creation tool that can help you create your products knowledge base with minimal changes i.e. “RANETO”. It was a real time saver for canUmeet knowledge base creation.
Wondering what it is and how to use Raneto for your docs creation? Here we go!! :)
Raneto is a Knowledge base platform for Node.js that uses static Markdown files to power the knowledge base. It can be called as a “static site generator” as it doesn’t require a database. All of your content is stored in the content folder in Markdown files and the entire knowledge base structure and content is generated by Raneto.
Markdown files stores contents that you want to display onto your knowledge base having an extension “.md”. We have several on-line markdown editor to help you create yo1ur .md files such as dillinger.io, stackedit.io
Coming back to Raneto, below are reason why it is an excellent source for your doc base creation:
- It is simple to use where you can create and manage an entire knowledge base using your personal favorite text editor.
- Raneto is a flat file CMS which means no database and no SQL queries nothing.
- It is a lightweight tool which makes it super fast for users.
- For templating purpose Raneto users Mustache.js
- As it is powered by bootstrap, it has a responsive default template.
- For code syntax highlighting it uses Highlight.js
- Powered by Lunr, Raneto provides a full text search for your knowledge base.
- Git-Hub flavored markdown.
Moving forward, first thing on your mind now is how to install raneto onto your system ? Believe me it’s real easy.
- Raneto installation requires Node.js v4.0.0 or later for successfull execution.
To have a look into list of services that provide Node hosting if you are looking to publish your knowledgebase online, please visit this link. (https://github.com/nodejs/node-v0.x-archive/wiki/Node-Hosting)
- Once you are completely sure you have met the requirements for Raneto installation, proceed further with the installation through below steps mentioned. It is recommended to create a new Git repository to store your documentation files and then install Raneto as a dependency into it. See the example/ directory for how this implementation works. - Switch to your existing or new project directory. - Add Raneto to your project via NPM's package.json file or downloading the latest version from the releases page. - In a terminal, run npm install to install the node dependencies. - To start Raneto, run npm start (or npm run start_win on Windows). - Visit http://localhost:3000 in your web browser. Start creating your own pages now.
Production Notes: When running a live site you’ll want to set the PORT env variable to 80 so you don’t need to add :3000 to the URL. This requires root privileges and is not recommended. Instead it is preferred to use a reverse proxy for security reasons. Heroku and other services handle this aspect for you, but you can implement your own reverse proxy with Nginx or Apache. See Related Projects for deployment scripts to use on your own servers. You can change the port anytime by setting the environment variable in your shell’s profile, or running in-line as below: $ PORT=1234 npm start
Some of the usage of Raneto are Authentication, Configuration, Creating and deleting page, Sorting and Customized homepage.
- To enable authentication in Raneto, from config.js file just change authentication to true and change the credentials to your desired name and password. Finally restart the server for your changes to take into effect.
- Raneto has provided full flexibility to edit its configuration from config.js file in the root directory. Just remember restarting the app after you finish changing config variables. You can also add custom variable and they will be available in template via .
Creating pages in Raneto is very simple.
Firstly identify the location where you are going to save your markdown files. Here in Raneto all your .md files must always go under content folder in the root of your application. Remember only the markdown files under the content folder will be recongnized. Depending on your need for categorization, you can also create various levels of subfolder under the root content folder.
What name you are using for your markdown file, the same name of file defines what URL is used to navigate to that particular page.
For an example, if you have your file name as ""accountcreation.md" Location: content/accountcreation.md URL: /accountcreation .
At the top of a page you can place a block comment to specify certain attributes like Title, description, sort of the page. Sort feature can help to set an order which you want to see first.
For Example: /* Title: Page Title Description: Provide a small description Sort: 1/2/3/..5 */ And congrats your page is created!!! :)
Similarly page deletion is also very simple in Raneto where you just need to delete that particular markdown file from the content folder. Remeber to change the sort order for other files if you have specified any.
If a page doesn’t have a sort order index, it is by default 0 at Raneto.
Raneto provides its default homepage which is its regular knowledgebase design. If you want to customize it according to your need, you can create an index.md file in the content folder which will be treated like a regular page.
As said before, Raneto is powered by Mustache.js . The default template views can be found in themes/default folder. You have full authorization to edit these themes according to your need. Below is the template structure.
- layout.html: This is the parent template which is edited first. - home.html: This is homepage template. - page.html: Single pages templating. - search.html: Search result template. - error.html: Template visible while Raneto encounters an error or cant find page. Once you are finished with template changing phase, restart the app.
All the images, CSS, JS files in Raneto are stored in the public folder from where it is served. Only files present in public folder are available to the public. To see list of template variables available for templating your personal knowledge base, please visit this link.(http://docs.raneto.com/templates/customizing-the-template)
Finally once finished with the changes as per your requirements, deploy it using Heroku or any cloud hosting platform.
If you want to report a bug, request a feature, contribute or translate Raneto? At the moment most things can be contributed via the main Raneto GitHub repository(https://github.com/gilbitron/Raneto) .
“YOUR KNOWLEDGE BASE IS READY”. Congrats!!