serve-markdown-it - sermit
Configurable static file server with markdown-it for parsing Markdown.
README & DOCS TODO
Installation
yarn global add serve-markdown-it
Developing
yarn gen-readme // update README.mdyarn docs // update DOCUMENTATION.mdyarn test // lint & mochayarn update-deps // bump all deps
Release History
See CHANGELOG.md for more information.
License
Distributed under the MIT license. See LICENSE.md for more information.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
API Reference
The standalone JSDoc reference can be found in DOCUMENTATION.md
Modules
- serve-markdown-it
sermit -
serve-markdown-it
.Description TODO.
Configurable static file server with markdown-it for parsing Markdown.
Functions
- getConfig(params) ⇒
Promise
Resolve the runtime configuration, loading the first user config file found. Searches directories up the path for any of the following files:
.sermitrc
.sermitrc.js
.sermitrc.json
.sermitrc.yaml
.sermitrc.yml
Any discovered user config file is merged with the default DefaultConfig object.
- mergeConfig(params) ⇒
Promise
Overrides the default configuration with a user config object. Deep options are replaced, shallow ones merged (i.e.
markdown-it
constructor defaults).- createServer(params) ⇒
Promise
Starts an HTTP server on the configured port, and serves static files out of the specified
basePath
. If thebasePath
is a file, only that file will be rendered, excluding any resolved assets.Files provided by the configured template are rendered from disk. Any URLs ending in
/raw
have the suffix removed and cause any matching file inbasePath
to be rendered like an asset. This allows file contents to be rendered with a link to the file itself.If a URL is not an asset or raw file, it is checked against the
matchMarkdownFileNames
regex on the provided Config object. Files that match are passed throughmarkdown-it
.Any remaining URLs are assumed to map to the
basePath
; if they are files, they are rendered as source within markdown code fences. Directories trigger the file explorer if allowed by the configuration.
serve-markdown-it
serve-markdown-it
.
sermit - Description TODO.
Configurable static file server with markdown-it for parsing Markdown.
License: MIT
Example (sermit help)
sermit path options Serve local files Commands: sermit print-config Log the merged configuration to the console sermit gen-config Generate a file sermit render Render local files to static HTML sermit serve path options Serve local files default Options: --log-level -l Log level increase to debug string choices: 'error' 'info' 'warn' 'debug' default: 'error' --path -p Root directory string required default: '/home/user/code/personal/serve-markdown-it' --help Show help boolean --version Show version number boolean --port Port number to spawn HTTP server on number required default: 8960 Examples: sermit gen-config > sermitrcjson Generate basic configuration
Example (sermit)
cli › ★ star read config from /sermitrcjsoncli › ★ star using template defaultcli › ★ star using md plugin markdown-it-smartarrowscli › ★ star using md plugin markdown-it-anchorcli › ★ star using md plugin markdown-it-highlightjscli › ★ star serving content from /home/user/code/personal/serve-markdown-itcli › ★ star listening at http://localhost:8960
Example (sermit gen-config > .sermitrc.json)
minify: true excludeGitIgnore: true template: name: 'serve-markdown-it-template-default' config: maxWidth: '960px' sections: contentHeader: true settings: true debug: true content: true order: 'settings' 'content' 'debug' explorer: icons: true columns: 'name' 'user' 'group' 'mode' 'type' 'size' dataTable: searchable: true sortable: true perPage: 25 perPageSelect: 10 25 50 100 fixedHeight: false layout: top: '{select}{search}' bottom: '{pager}' headerBar: false settingsBar: false dataTable: false md: typographer: true linkify: true html: true plugins: name: 'markdown-it-smartarrows' init: 'after' config: auto: true code: true name: 'markdown-it-anchor' config: permalink: true permalinkBefore: true permalinkSymbol: '§' init: 'after' name: 'markdown-it-highlightjs' config: auto: true code: true init: 'after'
Promise
getConfig(params) ⇒ Resolve the runtime configuration, loading the first user config file found. Searches directories up the path for any of the following files:
.sermitrc
.sermitrc.js
.sermitrc.json
.sermitrc.yaml
.sermitrc.yml
Any discovered user config file is merged with the default DefaultConfig object.
Kind: global function
Returns: Promise
- p - resolves with the final Config object.
Todo
- consider including
basePath
in search
Param | Type | Default | Description |
---|---|---|---|
params | object |
params. | |
[params.basePath] | string |
"cwd" |
path to start searching in. |
[params.configPath] | string |
path to pre-loaded user config file, required if config is provided. |
|
[params.config] | object |
user config file if already found, search is skipped if provided. |
Example
const config = await const state = configconst md configPath template = state if configPath l if || command === 'serve' || command === 'render' l mdpluginNames
Promise
mergeConfig(params) ⇒ Overrides the default configuration with a user config object. Deep options
are replaced, shallow ones merged (i.e. markdown-it
constructor defaults).
Kind: global function
Returns: Promise
- p - resolves with final config object.
See: getConfig
Param | Type | Description |
---|---|---|
params | Array |
[userConfig, userConfigPath, basePath] |
Example (usage within getConfig)
const getConfig = userConfig ? Bluebird : EXPLORER
Promise
createServer(params) ⇒ Starts an HTTP server on the configured port, and serves static files out of
the specified basePath
. If the basePath
is a file, only that file will
be rendered, excluding any resolved assets.
Files provided by the configured template are rendered from disk. Any URLs
ending in /raw
have the suffix removed and cause any matching file in
basePath
to be rendered like an asset. This allows file contents to be
rendered with a link to the file itself.
If a URL is not an asset or raw file, it is checked against the
matchMarkdownFileNames
regex on the provided Config object. Files
that match are passed through markdown-it
.
Any remaining URLs are assumed to map to the basePath
; if they are files,
they are rendered as source within markdown code fences. Directories trigger
the file explorer if allowed by the configuration.
Kind: global function
Returns: Promise
- p - resolves to koa instance.
Param | Type | Description |
---|---|---|
params | object |
params. |
params.basePath | string |
absolute path to the root content directory. |
params.config | Config |
config data. |
Example
const SERVE_HANDLER = async { const l port config path = argv const server = await server l l}