docula-core

docula-core

Docula is a knowledge base system based on open technologies. Keep your data in GitHub, but still have a rich UI, search and other services.

Features

• GitHub repository cloning and change detection.
• Documentation files in Markdown
• API documentation files in OpenAPI Json or YAML
• Category-based organization of supported documentation.
• Organizing metadata model in Redis data store.
• Storing files content in Redis file store.
• Indexing files content in ElasticSearch.
• Providing necessary node.js programming layout to build external APIs or User Interfaces.
• Providing React-base UI application for read access to a repository.
• Providing support for easy integration into existing Express.js based web sites.

Docula-Core provides core functionality to build services based on Docula

Other Docula modules:

• Docula-UI-React - React.js components for Docula public UI
• Docula-UI-Express - a glue for other modules to make including Docula to your node.js Express-based website a one-liner

Installation

Requires Node.js v5.9.1 or higher. Requires Redis. ElasticSearch is optional.

Using NPM

$ npm install docula-core --save

How To Use Docula-Core

1. Initialize Core

const Docula = require('docula-core');

const docula = new Docula({
  git: {
    remote_url: 'https://github.com/yourorg/yourrepo',
    local_path: '/var/docula/repositories/yourrepo'
  }
})

or

const docula = new Docula('/var/docula/config.json');

If you have some items in your configuration you want to configure via Environment, use additional parameter to Docula. These settings will override anything from previous config.

const docula = new Docula('config.json', {
  git: { token: '123X' }
});

2. Set up repository refreshing

Once initialized, your repository will not have any data unless explicitly synchronized. Synchronization procedure clones or pulls the repo if it's already there, and scans changes since last point remembered in database.

Normally this should be done once initially, and then as a result of a GitHub commit hook. But you also could set it up via scheduler if you host your git repo somewhere else or for any other reasons.

docula.refresh();

Config Options

• git - git repo settings section
  • remote_url - http/https/git/file URL of your git repository
  • local_path - path in a local filesystem for a repository to be cloned to
  • branch - (default: master) optionally different branch to use
  • token - (default: null) Git access token if repository requires it
• dataStore
  • redis - Redis access settings
    • host - (default: 127.0.0.1)
    • port - (default: 6379)
    • path - (default: null)
• fileStore
  • redis - Redis access settings for a file store
    • host - (default: 127.0.0.1)
    • port - (default: 6379)
    • path - (default: null)

Docula API

Docula uses Q promises, and most core methods return one.

Docula uses filesystem paths (relative to repo root) as IDs for articles, categories etc. Terms "path" and "id" are mostly interchangeable throughout Docula.

Main concepts are:

• Article - a file in a folder in a repo which is recognized by Docula (currently Markdown document or OpenAPI spec in YAML or Json). An Article must have a parent folder which is not a repository root. Only exception is special index.md file – it is supposed to be shown at a website home page.
• Category – a folder with associated properties (none currently, but later it might have an icon etc)

Docula instance methods:

• getObjectMetadata(path: string) - returns basic description for an object at a given path, be it a category, an article, OpenAPI document or whatever else Docula supports. Or null if nothing found.
• getAllCategories() - returns a promise with a tree structure of all categories currently known to the system.
• getArticles(categoryPath: string) - returns a list of articles under a given category.
• getFullArticle(articlePath: string) - returns a Buffer holding a file content for a given article.
• refresh() - begins synchronization procedure. Promise returned signals it's completion and status.
• getIndexArticleContent() - returns a Buffer holding content of an index.md file.

Tests

Tests for docula-core can be run using the command:

$ gulp test

Issues

Issues? Feature Requests? reported an issue.