docs-server

Docs-server

A server implementation which is used to build a 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

  /**
   * a middleware for setting response headers
   * This option will COVER headers option
   *
   * @param {Koa.Context} ctx
   * @param {Function} next
   */
  headerMiddleware: async function (ctx, next) {
    // do something

    // for example, You can create a whitelist for CORS origin headers
    const isInWhitelist = ctx.origin === 'https://github.com'
      || ctx.origin === 'http://example.com'

    if (isWhitelist) {
      ctx.set({
        'Access-Control-Allow-Origin': `${ctx.origin}`
      })
    }

    // DON'T forget invoke next()
    await next()
  }
})

• 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)

  • Two choices to set response headers

    1. headers: set a headers object that will be used to set response header

    2. headerMiddleware: default middleware will be replaced by your headerMiddleware setting, and DON'T forget invoke next() in middleware function body

• 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

Changelog

1.4.1 (2018-08-15)

Bug Fixes

• adjust max-age of menu route (d0b7529)

<a name="1.4.0"></a>