docs-server

Docs-server

A server which is used to build a kind of microservices for docs system.

Feature

• Perform automatic markdown searching and generate correct dynamic routes according to the root path of your project.

• Support multiple-level documentation routes.

• Support for specifying additional static resources routes.

• Support for customizing all docs routes

• Support for customizing docs response headers

• Support for specifying minimum response size in bytes to turn on gzip

Installing

# yarn
yarn add docs-server

# npm
npm i docs-server

Usage

• Easy running

const DocsServer = require('docs-server')

// It should be running at http://localhost:8800 by default
const app = new DocsServer()

• ( Optional ) You can specify your custom configuration.

const resolve = require('path').resolve
const DocsServer = require('docs-server')

// Notice: all options is optional
const app = new DocsServer({
  // should be nodejs current working directory
  // recommend you keep default value (your project root path)
  cwd: resolve(__dirname, './'),

  // the output path of catalog files (based on current working directory)
  dest: resolve(__dirname, './menu.json'),

  // your server running port
  port: '8800',

  headers: {
    // default value: '*'
    'Access-Control-Allow-Origin': '*',

    // default value: 'origin'
    'vary': 'origin',

    // Notice: server will set 'Content-Type' header by default

    // other response headers you want set
    'Access-Control-Allow-Methods': 'GET,POST'
  },

  // minimum response size in bytes to turn on gzip
  // default value: 1 bytes
  threshold: 1

  // extra static resource routes
  extra: [
    {
      route: '/test', // eg. http://locahost:8800/test
      middleware: async (ctx, next) => {
        // do something
      }
    }
  ],

  /**
   * docs routes filter, will not filter your extra routes and menu.json
   * @param {String} origin: origin routes, equal to your docs path based on root
   * @return {String} formative string, your expected routes syntax
   */
  // origin: 2018/123456-aa/123456-aa.md ----> formative result: /writings/aa
  filter: (origin) => {
    const removeShortDate = origin.replace(/\/{0}(\d{6}-)+/g, '')
    const removeInitialYear = removeShortDate.replace(/^\d{4}/, '')
    const removeRepeat = removeInitialYear.replace(/^\/\S+\//, '')
    const removeExtension = removeRepeat.replace(/\.md$/, '')
    return `writings/${removeExtension}`
  }
  // request /writings/aa, get origin data 2018/123456-aa/123456-aa.md
})

• Notice:

  • All options is optional

  • default filter will just remove docs file extension name

  • custom filter MUST return a string type value, and it will be used to only generate docs routes (excluding extra routes and menu.json)

• Test your building

# test your server
curl -v http://localhost:8800  # response from /
curl -v http://localhost:8800/doc/sample # response from /doc/sample

CHANGELOG

CHANGELOG