docula-ui-express

docula-ui-express (https://docu.la)

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-UI-Express glues together other Docula modules to create rich UI and REST API to be included into an Express.js-based app

Other Docula modules:

• Docula-Core - core functionality to build services based on Docula
• Docula-UI-React - React.js components for a Docula user interface

Install

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

Using NPM

$ npm install docula-ui-express --save

How To Use Docula-ui-express

const Docula = require('docula-core');
const DoculaExpress = require('docula-ui-express');
const express = require('express');
const app = express();

const API_BASE = '/api/';
const REPO_PATH = '/var/docula/repositories/yourrepo';

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

app.use(API_BASE, DoculaExpress.api(docula));

app.use('/', DoculaExpress.ui({
  apiBase: API_BASE,
  disqusKey: DISQUS_KEY
  assets: {
    sourceDir: REPO_PATH
  }
}));

app.listen(8080, function() {
  console.info(`App listening on port 8080`);
  docula.refresh();
});

Categories

{
    "x-categories": [
        {
          "id": "categoryId",
          "title": "Category"
        },
        {
          "id": "categoryId2",
          "title": "Category2"
        }
    ]
 }

Code Examples

{
    "x-engine": {
        "php": {
          "title": "PHP",
          "is_default": true
        },
        "java": {
          "title": "Java",
          "is_default": false
        }
     }
 }
 
 "paths": {
     "/endpoint": {
         "post": {
            "x-engine-example": {
                "php": "{\n php code \n}",
                "java": "{\n java code \n}"
            }
         }
     }
 }

Docula Core configuration

see Docula-Core

UI configuration

• apiBase - base URL where API resides
• assets - static files management configuration
  • sourceDir - folder path where static files reside.
  • extensions - (default: ['png', 'jpg', 'jpeg', 'svg', 'gif', 'bmp']) - a list of file extensions which would be ignored by a serverside router, and so instead of returning "index.html" app would look for this file in sourceDir. This is necessary if you want to keep images or other attachments along with the articles in a repository.

Api Endpoints

(post) /invalidate: Clone or update GitHub repository

(get) /category: List categories tree

(get) /category/{path}: Get a list of articles under Category specified by path

(get) /article/{path}: Get full content of an article specified by path

(get) /search?query={text}: Search articles (works only is ES is enabled)

Tests

Tests for Docula-Ui-Express can be run using the command:

gulp test