Markview

A simple markdown (kramdown) preview server meant as a development tool.

Getting started

The default implementation uses kramed and highlight to render pages under the current working directory. Pages are styled using github style as provided by github-markdown-css and highlight.js packages. If this is what you need, running the server is very simple.

Install

npm install -g markview

Run

cd my-project/ && markview

You can now render files in your browser (http://localhost:8008/path/to/your/file.md)

By default, the server uses port 8008. You can override this with the environment variable MARKVIEW_PORT

cd my-project/ && MARKVIEW_PORT=8080 markview

Customizing the preview server

Run in another app

In your project (to be used as a development tool)

npm install -D markview

In your script

var myapp = require('express')();

// ... myapp related stuff...

try {
  var markview = require('markview')();
  myapp.use('/preview', markview);
} catch (e) { /* devDependencies not installed */ }

// ... more myapp related stuff...

myapp.listen(8080);

// your project's README.md is viewable at http://localhost:8080/preview/README.md

Options

Options are passed in as an object. Defaults options are exposed by the module for convenience.

var markview = require('markview');

// default options
markview.DEFAULTS;

markview({ /* options */ });

css

Type: Object

Map url paths to the absolute path of css files to be served under cssMount. url paths are relative (no leading slash).

The object SHOULD also set the key _order to an array of url paths (keys of the same object) to provide the order of <link> tags in generated html pages. If omitted, a default order will be obtained with a for ... in loop (which, by standard, is undefined). A warning will be printed to stdout if _order is not set.

var resolve = require('path').resolve;

var markview = require('markview');

markview({
  // This is the default.
  css: {
    'markdown.css':
      require.resolve('github-markdown-css'),
    'highlight.css':
      resolve(require.resolve('highlight.js'), '../..', 'src/styles/github.css'),
    'overrides.css':
      resolve(__dirname, 'overrides.css'),
    _order: [
      'markdown.css',
      'highlight.css',
      'overrides.css' ]
  }
});

Extending defaults:

var markview = require('markview');

markview({
  css: Object.assign({}, markview.DEFAULTS.css, {
    'my-overrides.css': resolve(__dirname, 'my-overrides.css'),
    _order: markview.DEFAULTS.css._order.concat([ 'my-overrides.css' )
  })
});

cssMount

Type: string Default: /_css

Provide the mount point to serve css files under. Must start with a slash.

renderer

Type: function (data, callback) {}

Provide your own renderer. The default renderer uses kramed for kramdown github-style markdown files, combined with highlight.js for code syntax highlighting.

var markview = require('markview');

markview({
  renderer: (data, done) => done(data) // A 'do nothing' renderer.
});

files

Type: Object

A map of url paths associated with markdown files location. Leading slashes in keys are optionals.

By default, the application serves all files ending with .md or .markdown under the current working directory.

An Entry can be:

• a file: the value is an absolute path to the file.

  var markview = require('markview');
  
  markview({
    files: { 'README.md': __dirname + '/README.md' }
  });

• a directory: the value is an object defining the absolute root path for files under this directory, with an optional filter function to define which files are to be rendered in this directory. (by default, the filter function allows only .md and .markdown extensions)

  var markview = require('markview');
  
  // This is the default
  markview({
    '/': {
      root: process.cwd(),
      filter: (path) => /\.(md|markdown)$/.test(path)
    }
  });

Bugs

Use the project's github Issues system to file bugs.

DO NOT FILE BUGS about SECURITY or PERFORMANCE

Please be aware that this project is intended for DEVELOPMENT use ONLY and is kept simplistic on purpose. As such, any security or performance issues won't be addressed at all.

License

Copyright (c) 2016, Raphaël Bois Rousseau. (MIT Licensed)

See LICENSE for more informations.