A server implementation which is used to build a docs system.
I create this project just for implementing my docs back-end simply. It's unusual back-end module which is used to build disposable micro-server.
I use this project in some platform where user has no write permission on runtime mode, so this project don't support for adding new docs when server is running. This is intentional. You can use this project to your own documentation module If you have same situation.
-
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
-
Support
static
mode, You can only generateJSON
static files without server building.
# yarn
yarn add docs-server
# npm
npm i docs-server
- Building server from easy way
const DocsServer = require('docs-server')
// It should be running at http://localhost:8800 by default
const app = new DocsServer()
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',
// headersMiddleware option can override this Headers option
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 only used to generate docs routes (excluding
extra routes
andmenu.json
) -
Two choices to set response headers
-
headers: set a headers object that will be used to set response header
-
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
const DocsServer = require('docs-server')
// JSON file path will be generated from original markdown files path
new DocsServer({
mode: 'static',
// Default behavior is only remove files extension
staticNormalize (origin) {
// do something you like
return /* for example */ origin.replace(/\.md$/, '')
}
})
In the static mode, mode
option is required, and staticNormalize
is optional. staticNormalize
option is used to specify what you want to change based on markdown file path.
The sample file under static mode is here