smart-json2md

A simple utility to convert plain JSON files to hierarchical Markdown documents with intelligent structuring.

Features

• Automatically converts JSON objects to Markdown with headings based on hierarchy
• Supports nested objects with appropriate heading levels
• Handles deep structures by converting to lists when exceeding configured heading levels
• Arrays are displayed as Markdown lists
• Intelligently processes arrays of objects with common structure
• Configurable minimum and maximum heading levels
• Option to use ordered or unordered lists for deep structures
• Option to include type information for values
• Easy to use CLI and programmatic API

Installation

1npm install smart-json2md

Or globally:

1npm install -g smart-json2md

CLI Usage

1smart-json2md input.json -o output.md

Options

Usage: smart-json2md [options] <input>

Convert JSON files to Markdown with automatic hierarchy

Arguments:
  input                  Input JSON file path

Options:
  -V, --version          output the version number
  -o, --output <output>  Output Markdown file path
  -t, --types            Include type information
  -l, --max-level <level>  Maximum heading level (1-6) (default: "6")
  -m, --min-level <level>  Minimum heading level (1-6) (default: "1")
  -n, --no-process-arrays  Disable intelligent array processing
  -p, --pretty           Make output more readable with extra spacing
  -r, --ordered-lists    Use ordered lists for content beyond max heading level
  -h, --help             display help for command

Programmatic Usage

1import { jsonToMarkdown, convertJsonFileToMarkdown } from 'smart-json2md';
2
3// Convert a JSON object directly
4const json = {
5  person: {
6    name: 'John Doe',
7    age: 30,
8    address: {
9      street: '123 Main St',
10      city: 'Anytown',
11      location: {
12        latitude: 40.7128,
13        longitude: -74.0060,
14        details: {
15          region: 'Northeast',
16          country: 'USA'
17        }
18      }
19    },
20    hobbies: ['reading', 'hiking', 'coding'],
21    contacts: [
22      { type: 'email', value: 'john@example.com' },
23      { type: 'phone', value: '555-1234' }
24    ]
25  }
26};
27
28// Basic conversion
29const markdown = jsonToMarkdown(json);
30console.log(markdown);
31
32// Advanced options
33const advancedMarkdown = jsonToMarkdown(json, {
34  minHeadingLevel: 2,      // Start with h2 headings instead of h1
35  maxHeadingLevel: 4,      // Only use headings up to h4
36  includeTypes: true,      // Include data types
37  useOrderedLists: true,   // Use numbered lists for deep structures
38  processArrayObjects: true // Enabled by default
39});
40console.log(advancedMarkdown);
41
42// Convert a file
43await convertJsonFileToMarkdown('input.json', 'output.md', {
44  minHeadingLevel: 1,
45  maxHeadingLevel: 4,
46  useOrderedLists: true
47});

Example: Deep Structure Handling

Given a deeply nested JSON:

1{
2  "level1": {
3    "level2": {
4      "level3": {
5        "level4": {
6          "level5": {
7            "level6": {
8              "level7": "This is very deep"
9            }
10          }
11        }
12      }
13    }
14  }
15}

With maxHeadingLevel: 4 and useOrderedLists: true, the result will be:

1# level1
2
3## level2
4
5### level3
6
7#### level4
8
91. **level5**:
10  
11  1. **level6**:
12    
13    1. **level7**: This is very deep
14

Notice how levels beyond the 4th (max heading level) automatically convert to ordered lists.

Advanced Options

The library provides several options for customizing the conversion:

• minHeadingLevel: Starting heading level (1-6, default: 1)
• maxHeadingLevel: Maximum heading level (1-6, default: 6)
• includeTypes: Add type information for values
• processArrayObjects: Enable smart processing of arrays containing objects
• useOrderedLists: Use numbered lists instead of bullet points for deep structures
• valueFormatter: Custom function to format specific values

License

MIT