A markdown server.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests
texts
.eslintrc
.gitignore
LICENSE
README.md
cache.js
index.js
package-lock.json
package.json

README.md

micro-markdown

A markdown server.

⚠️ Under active development; not stable! These docs are incomplete. ⚠️

micro-markdown is a markdown server. It serves both markdown files and markdown strings. It's built on top of Zeit's micro, and uses a redis cache by default. In the spirit of micro, micro-markdown tries to be as async as possible.

micro-markdown can be used as an API for rendering and serving markdown, or as a server for a markdown based website.

Markdown files

To serve a markdown file, add a file to the ./texts directory (this path is customizable).

<!-- ./texts/hello.md -->

# Hello, world.

I am some markdown.
// ./server.js
const server = require('micro-markdown')
/**
 * Start the server.
 * The rendered HTML will be available at `http://localhost:3000/mm/api/v1/html/hello`
 */
server().listen(3000)

Custom handlers

You can also pass a route handlers directly to micro-markdown:

// ./server.js
const server = require('micro-markdown')
/**
 * Start the server.
 * The rendered HTML will be available at `http://localhost:3000/mm/api/v1/html/example`
 */
server({
  routes: {
    example: {
      handler: () => ({ markdown: '# Hello, example.' })
    }
  }
}).listen(3000)

API

By default, micro-markdown renders three endpoints for each route:

  • /mm/api/v1/html/:endpoint: Returns the rendered HTML for :endpoint
  • /mm/api/v1/json/:endpoint: Returns a JSON object representing the provided markdown for :endpoint.
  • /mm/api/v1/raw/:endpoint: Returns the raw markdown string for :endpoint.

Route maps

You can pass route maps to micro-markdown to mirror existing endpoints. This is helpful if you want to use micro-markdown to serve a markdown-based website.

// ./server.js
const server = require('micro-markdown')
/**
 * Start the server.
 * The rendered HTML will be available at `http://localhost:3000/example`
 */
server({
  routes: {
    example: {
      handler: () => ({ markdown: '# Hello, example.' })
    }
  },
  routeMaps: {
    default: route => {
      // Resolve `/mm/api/v1/html/${foo}` to `/${foo}`
      return route.indexOf('/mm') === 0
        ? {}
        : { route: `${route}`, target: 'html' }
    }
  }
}).listen(3000)

Caching

Rendered markup is cached by default, using redis. To use the redis cache, provide the following environment variables:

REDIS_HOST="YOUR_REDIS_HOST" # Default `redis`
REDIS_PORT="YOUR_REDIS_PASSWORD" # Default `6379`
# Optional
REDIS_PASSWORD="YOUR_REDIS_PASSWORD"

By default, micro-markdown will flush the redis cache the first time it is called.

Why?

I wanted a simple server that would dynamically render and route markdown.

I tried other options:

  • Static site: Renders markdown, but requires a build.
  • SSR with React, Vue etc.: There are great tools for this. I couldn't find a good option that would let my dynamically render flat markdown files to custom routes, though.