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.jsconst server = /** * Start the server. * The rendered HTML will be available at `http://localhost:3000/mm/api/v1/html/hello` */
Custom handlers
You can also pass a route handlers directly to micro-markdown
:
// ./server.jsconst server = /** * Start the server. * The rendered HTML will be available at `http://localhost:3000/mm/api/v1/html/example` */
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.jsconst server = /** * Start the server. * The rendered HTML will be available at `http://localhost:3000/example` */
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.