# mdware

> Serve Markdown documents as static content. Based on Nate Silva's node-docserver.

Latest version **0.2.5** (published 2013-07-17) · 0 weekly downloads

## Install

```sh
npm install mdware
pnpm add mdware
yarn add mdware
bun add mdware
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.5 |
| Published | 2013-07-17 |
| First published | 2013-07-16 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | * |
| Dependencies | 5 |
| Known vulnerabilities | 0 (+15 in 3 direct dependencies) |
| Install scripts | no |
| Author | Tom Ashworth |
| Maintainers | phuu |
| Keywords | static, web, server, markdown, middleware |

## Links

- npm: https://www.npmjs.com/package/mdware
- Repository: https://github.com/phuu/mdware
- npm.io page: https://npm.io/package/mdware

## Dependencies (5)

- [mime](https://npm.io/package/mime.md) ~1.2.7
- [async](https://npm.io/package/async.md) ~0.2.9
- [lodash](https://npm.io/package/lodash.md) ~1.3.1
- [marked](https://npm.io/package/marked.md) ~0.2.9
- [json-front-matter](https://npm.io/package/json-front-matter.md) ~0.1.3

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.2.5 (latest) — 2013-07-17
- 0.2.4 — 2013-07-17
- 0.2.3 — 2013-07-17
- 0.2.2 — 2013-07-16
- 0.2.1 — 2013-07-16
- 0.2.0 — 2013-07-16

## README

# 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](https://github.com/natesilva/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

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

```markdown
{{{
  "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.

---
_Source: https://npm.io/package/mdware · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._