Skip to content

Latest commit

 

History

History
301 lines (265 loc) · 9.42 KB

DOCUMENTATION.md

File metadata and controls

301 lines (265 loc) · 9.42 KB
Raw

Modules

http-server-md

httpmd - http-server-md.

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:

  • .httpmdrc
  • .httpmdrc.js
  • .httpmdrc.json
  • .httpmdrc.yaml
  • .httpmdrc.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.

http-server-md

httpmd - http-server-md.

Description TODO.

Configurable static file server with markdown-it for parsing Markdown.

License: MIT
Example (httpmd help)

httpmd [path] [options]

Serve local files

Commands:
  httpmd print-config            Log the merged configuration to the console
  httpmd gen-config              Generate a new configuration file
  httpmd render                  Render local files to static HTML
  httpmd 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/http-server-md']
  --help           Show help                                           [boolean]
  --version        Show version number                                 [boolean]
  --port           Port number to spawn HTTP server on
                                             [number] [required] [default: 8960]

Examples:
  httpmd gen-config > .httpmdrc.json  Generate basic configuration

Example (httpmd)

[cli] › ★  star      read config from /.httpmdrc.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/http-server-md
[cli] › ★  star      listening at http://localhost:8960

Example (httpmd gen-config > .httpmdrc.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:

  • .httpmdrc
  • .httpmdrc.js
  • .httpmdrc.json
  • .httpmdrc.yaml
  • .httpmdrc.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}`)}`
    )
  )
}