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

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

API Reference

The standalone JSDoc reference can be found in DOCUMENTATION.md

Modules

Functions

serve-markdown-it

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

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 (argv) => {
  const { l, port, config, path } = argv
  const server = await createServer({ basePath: path, config })

  server.listen(port)

  l.star('serving content from %s', colors.underline(path))
  l.star(
    '%s',
    colors.cyan.underline(
      `listening at ${colors.bold(`http://localhost:${port}`)}`
    )
  )
}