Write a post
Published Dec 08, 2015

How to Convert JSON to Markdown using json2md

How to Convert JSON to Markdown using json2md

I love and use both JSON and Markdown in my projects. Each npm package requires a package.json file which is obviously written in JSON format. Also, good projects have good documentation. My favorite language for writing docs is Markdown.

But I don't really write Markdown files. I do write docs, but they are stored in the code (JSDoc comments). I automated the process of generating Markdown docs using Blah. However, sometimes these documentation templates are not enough.

That's why I created json2md which is the bridge between JSON and Markdown languages. Integrating this package with my Blah templates, I can write custom things in the final documentation result using JSON inputs in my package.json (or another JSON file).

How to use

Everything starts with a npm i json2md to download and install the json2md package locally. Then you can require it in your Node.js apps or even on the client-side (in the browser).

For example, to create a Markdown image result, you have to do this:

var json2md = require("json2md");

var myImg = json2md({
    img: {
        source: "http://example.com/image.png"
      , title: "My image"

This will output ![My image](http://example.com/image.png).

Here is another example which is more complex:

// Dependencies
var json2md = require("json2md");

    { h1: "JSON To Markdown" }
  , { blockquote: "A JSON to Markdown converter." }
  , { img: [
        { title: "Some image", source: "https://example.com/some-image.png" }
      , { title: "Another image", source: "https://example.com/some-image1.png" }
      , { title: "Yet another image", source: "https://example.com/some-image2.png" }
  , { h2: "Features" }
  , { ul: [
        "Easy to use"
      , "You can programatically generate Markdown content"
      , "..."
  , { h2: "How to contribute" }
  , { ol: [
        "Fork the project"
      , "Create your branch"
      , "Raise a pull request"

This will generate:

# JSON To Markdown
> A JSON to Markdown converter.

![Some image](https://example.com/some-image.png)

![Another image](https://example.com/some-image1.png)

![Yet another image](https://example.com/some-image2.png)

## Features

 - Easy to use
 - You can programatically generate Markdown content
 - ...

## How to contribute

 1. Fork the project
 2. Create your branch
 3. Raise a pull request

And this is not all! You can create your custom converters. Let's suppose you have an input like { sayHello: "World" }. If you want to generate a Hello World! output, you can do:

json2md.converters.sayHello = function (input) {
     return "Hello " + input "!";

This basically extends the converters object and adds your custom converter.

Check out json2md on GitHub.
I'm sure there are a lot of things to improve. Feel free to ask questions, open issues and contribute!

Discover and read more posts from Johnny B. (Ionică Bizău)
get started
Enjoy this post?

Leave a like and comment for Johnny