serve-markdown-it

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.md
yarn docs // update DOCUMENTATION.md
yarn test // lint & mocha
yarn 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 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.

sermit - `serve-markdown-it`.

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 new configuration 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 > .sermitrc.json  Generate basic configuration

Example (sermit)

[cli] › ★  star      read config from /.sermitrc.json
[cli] › ★  star      using template default
[cli] › ★  star      using md plugin markdown-it-smartarrows
[cli] › ★  star      using md plugin markdown-it-anchor
[cli] › ★  star      using md plugin markdown-it-highlightjs
[cli] › ★  star      serving content from /home/user/code/personal/serve-markdown-it
[cli] › ★  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'
      }
    ]
  }
}

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.

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 getConfig({ basePath: basePath })
const { state } = config
const { md, configPath, template } = state

if (configPath) {
  l.star('read config from %s', colors.bgGreen.black(configPath))
}

if (_isEmpty(command) || command === 'serve' || command === 'render') {
  l.star('using template %s', colors.cyan(template.name))

  md.pluginNames.forEach((name) => {
    l.star('using md plugin %s', colors.yellow(name))
  })
}

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

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 = ({ basePath, configPath, config: userConfig }) => (
  (userConfig
    ? Bluebird.resolve({ config: userConfig, filepath: configPath })
    : EXPLORER.search(basePath))
    .then(({ config, filepath }) => [config, filepath, basePath])
    .catch(() => [DEFAULT_CONFIG, null, basePath])
    .then(mergeConfig)
    .then(normalizeConfig)
    .then(validateConfig)
    .then(loadTemplate)
)

createServer(params) ⇒ `Promise`