Ionică Bizău

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: ""
      , title: "My image"

This will output ![My image](

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: "" }
      , { title: "Another image", source: "" }
      , { title: "Yet another image", source: "" }
  , { 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](

![Another image](

![Yet another image](

## 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! ✨

Have feedback on this article? Let @IonicaBizau know on Twitter.

Have any questions? Feel free to ping me on Twitter.