mdware

mdward

Serves Markdown documents as static content. Acts as middleware for Connect and Express.

Use this to compile a folder full of Markdown documents (and its sub-folders) to be served as though they were static content.

Based on heavily Nate Silva's node-docserver. Thanks Nate!

Installation

npm install mdware

Features

• Handles Github-Flavored Markdown, using the marked package.
• In-memory caching that can easily be replaced by a custom cache module
• Can handle requests for an entire site, or just one subdirectory of a site.

Example

var express = require('express'),
    mdware = require('mdware');
 
var app = express();
app.use(mdware({
  dir: __dirname + '/docs',  // serve Markdown files in the docs directory...
  url: '/'}                  // ...and serve them at the root of the site
));
app.use(function (req, res) {
  res.send(req.mdware.html);
});
app.listen(3000);
 
console.log(mdware.version + ' listening on port 3000');

Mapping of URLs to Markdown files

Place Markdown files with the extensions .md or .mdown in your docs directory. (You can override these file extensions; see below for details.) Organize the directory any way you like, with any number of subdirectories.

Each directory can have an index.md (or index.mdown) file that will be served if the user requests the directory name.

Using the data

mdware attaches the data it compiles to the request object so that you can use it in whatever template you like. It has html, title and markdown properties.

Front matter

mdware support JSON fontmatter.

{{{
  "layout": "post",
  "tags": ["something", "nice"]
}}}
 
# My post
 
Hello, world.

It's accessible via req.mdware.attributes.

Directory structure example

For this example, assume the following directory structure:

docs/
├── index.md
├── README.md
├── template.html
└── api/
    ├── index.md
    ├── template.html
    └── v1.0/
        └── index.md

Example URLs

Given the “Using Express” example code and the directory structure shown above, a request for http://localhost:3000/ would return docs/index.md (converted to HTML, of course).

File extensions are handled automatically. In this example, the README file can be requested as http://localhost:3000/README or http://localhost:3000/README.md.

Likewise, the api/index.md file can be requested as http://localhost:3000/api/, http://localhost:3000/api/index.md, or even http://localhost:3000/api/index.

API

mdware(options)

Returns the mdware middleware, which is compatible with Connect, Express, Union and Flatiron.

dir

The directory where your Markdown documents are located.

example: { dir: __dirname + '/docs' }

url

The URL from which your documents should be served.

example (mdware handles the root level of the web site): { url: '/' }

example (mdward handles URLs under /docs): { url: '/docs/' }

cache

Override the caching subsystem. The default uses an in-memory cache.

To disable caching, set this to false. (You must use false. “Falsy” values like 0 or undefined will not work.)

No other subsystems are provided, but there is an example using Redis in the examples subdirectory.

example: {cache: YourCacheClass}

FAQ

Q: How does the cache work?

mdware aggressively caches the rendered, HTML form of your documents.

The first time a document is requested, mdware has to read it from disk (along with any template) and render it to HTML. On subsequent requests for the same document, it will be served from cache, which should be extremely fast.

In addition, requests that result in a 404 error are cached, so once mdware searches for a document and doesn’t find it, it won’t waste time looking for that document again.

By default, once a document is cached, mdware will never re-read that document; the cached version will always be served until you reload the server.

You also have the option to disable caching by passing false as the cache option.

If you enable the experimental watch option, the cache is emptied every time a change is detected in your docs directory or any of its subdirectories. Because it may be resource-intensive, this option is turned off by default. Enabling it when you have a large set of documents or subdirectories may exhaust available file handles. If you only have a few documents or subdirectories, feel free to try it out. Contributions to improve this feature are welcome.

The command-line interface is not intended as a production web server. Rather, it’s a quick way to read local folders containing documentation.