darkdown-to-markdown

Convert Darkdown format to GitBook-compatible Markdown with comprehensive migration tools.

Darkdown is a custom markdown format used by platforms like DeveloperHub. This package migrates Darkdown syntax to standard GitBook-compatible markdown.

What is Darkdown?

Darkdown is an extended markdown format that includes custom syntax for:

• Custom callouts (info, warning, danger boxes)
• Tab groups and code blocks
• Auto-linking
• Plugin blocks
• Custom image syntax
• Variables

This package converts all these custom formats to GitBook-compatible syntax.

Features

• 🔄 Complete Migration - Convert Darkdown syntax to standard/Gitbook Markdown
• 🔗 Smart Link Resolution - Automatically fix and track internal links
• 🖼️ Image Handling - Download and organize external images
• 📊 Comprehensive Reporting - Detailed HTML and JSON audit reports
• 📚 SUMMARY.md Generation - Automatic table of contents creation
• ⚙️ Highly Configurable - Customize every aspect of the migration
• 🧩 Modular Architecture - Use individual transformers programmatically
• ✅ Validation Tools - Verify documentation integrity post-migration

Installation

Global Installation (CLI)

npm install -g darkdown-to-markdown

Local Installation (Library)

npm install darkdown-to-markdown

Quick Start

CLI Usage

# Basic migration
darkdown-to-markdown migrate ./source ./destination

# Generate SUMMARY.md
darkdown-to-markdown summary ./docs

# Validate documentation
darkdown-to-markdown validate ./docs

# Initialize configuration
darkdown-to-markdown init

Programmatic Usage

const { migrate, generateSummary } = require('darkdown-to-markdown');

// Migrate files
await migrate({
  source: './source',
  destination: './docs',
  headingStrategy: 'gitbook_standard',
  downloadImages: true,
  generateReports: true
});

// Generate SUMMARY.md
await generateSummary({
  docsDir: './docs',
  outputFile: 'SUMMARY.md'
});

CLI Commands

migrate <source> [destination]

Migrate Darkdown files to Markdown.

Options:

• -c, --config <path> - Path to config file
• --no-reports - Skip generating audit reports
• --no-images - Skip downloading images
• --heading-strategy <strategy> - Heading adjustment strategy (default: gitbook_standard)
• --preserve-structure - Preserve original directory structure
• -v, --verbose - Enable verbose logging

Examples:

# Migrate to current directory
darkdown-to-markdown migrate ./source

# Migrate to specific destination
darkdown-to-markdown migrate ./source ./docs

# Skip image downloads
darkdown-to-markdown migrate ./source --no-images

# Use custom config
darkdown-to-markdown migrate ./source -c ./custom-config.json

summary <docs-dir>

Generate SUMMARY.md from documentation structure.

Options:

• -o, --output <file> - Output file name (default: SUMMARY.md)
• -s, --structure <file> - Custom doc structure file
• -v, --verbose - Enable verbose logging

Examples:

# Generate SUMMARY.md
darkdown-to-markdown summary ./docs

# Custom output file
darkdown-to-markdown summary ./docs -o TOC.md

validate <docs-dir>

Validate documentation structure and links.

Options:

• -s, --structure <file> - Custom doc structure file
• -v, --verbose - Enable verbose logging

Examples:

# Validate documentation
darkdown-to-markdown validate ./docs

init

Create a default configuration file.

Options:

• -f, --force - Overwrite existing config file

Examples:

# Create .darkdownrc.json
darkdown-to-markdown init

Configuration

Create a .darkdownrc.json file in your project root:

{
  "migration": {
    "headingStrategy": "gitbook_standard",
    "trackLinks": true,
    "downloadImages": true,
    "preserveStructure": false
  },
  "transformers": {
    "callouts": {
      "typeMap": {
        "note": "info",
        "error": "danger",
        "warning": "warning",
        "success": "success"
      }
    },
    "codeBlocks": {
      "languageMap": {
        "yaml": "YAML",
        "json": "JSON",
        "xml": "XML"
      }
    }
  },
  "reports": {
    "outputDir": "migration-reports",
    "formats": ["html", "json"],
    "detailedIssues": true
  },
  "summary": {
    "outputFile": "SUMMARY.md",
    "structureFile": "doc_structure.js"
  }
}

Heading Strategies

• gitbook_standard - Promote H2→H1, H3→H2, etc. (recommended for GitBook)
• promote_all - Promote all headings by one level
• demote_h1 - Demote only H1 to H2
• none - Keep headings unchanged

Programmatic API

Core Functions

migrate(options)

Perform a complete migration.

const { migrate } = require('darkdown-to-markdown');

const result = await migrate({
  source: './source',
  destination: './docs',
  headingStrategy: 'gitbook_standard',
  downloadImages: true,
  trackLinks: true,
  generateReports: true,
  preserveStructure: false,
  verbose: false
});

console.log(result);
// {
//   totalFiles: 150,
//   linksFixed: 423,
//   linksFailed: 12,
//   imagesProcessed: 87,
//   reportsPath: './migration-reports'
// }

generateSummary(options)

Generate SUMMARY.md file.

const { generateSummary } = require('darkdown-to-markdown');

const result = await generateSummary({
  docsDir: './docs',
  outputFile: 'SUMMARY.md',
  structureFile: 'doc_structure.js'
});

console.log(result);
// {
//   stats: {
//     totalFiles: 150,
//     foundFiles: 148,
//     missingFiles: 2,
//     coverage: '98.67%'
//   }
// }

validate(options)

Validate documentation structure.

const { validate } = require('darkdown-to-markdown');

const result = await validate({
  docsDir: './docs',
  structureFile: 'doc_structure.js'
});

console.log(result);
// {
//   isValid: false,
//   brokenLinks: 3,
//   missingFiles: 2,
//   orphanedFiles: 5
// }

Quick Helper Functions

quickMigrate(source, destination, options)

Simplified migration with sensible defaults.

const { quickMigrate } = require('darkdown-to-markdown');

await quickMigrate('./source', './docs', {
  headingStrategy: 'gitbook_standard'
});

quickSummary(docsDir, options)

Simplified summary generation.

const { quickSummary } = require('darkdown-to-markdown');

await quickSummary('./docs', {
  outputFile: 'SUMMARY.md'
});

Using Individual Transformers

const { transformers } = require('darkdown-to-markdown');

let content = fs.readFileSync('file.md', 'utf-8');

// Apply individual transformers
content = transformers.callouts.convert(content, 'file.md');
content = transformers.codeBlocks.normalize(content, 'file.md');
content = transformers.links.fix(content, 'file.md');

Custom Reporters

const { reporters } = require('darkdown-to-markdown');

const htmlReporter = new reporters.HtmlReporter({
  outputDir: './reports'
});

await htmlReporter.generate(auditData);

What Gets Converted?

Frontmatter

• Cleans null/empty values
• Normalizes boolean strings
• Validates YAML structure

Code Blocks

• Converts ~~~ to standard ```
• Normalizes language tags
• Handles plugin code blocks

Callouts

Converts custom callouts to GitBook hints:

{% callout type="warning" title="Important" %}
Content here
{% /callout %}

Becomes:

{% hint style="warning" %}
**Important**

Content here
{% endhint %}

Links

• Fixes [auto$](url) style links
• Resolves internal links
• Tracks broken links
• Extracts titles from frontmatter

Images

• Downloads external images
• Organizes in .gitbook/assets/
• Converts custom image syntax
• Adds figure tags with captions

Tables

• Converts custom table syntax
• Preserves standard markdown tables

Tabs & Code

• Converts tab blocks to GitBook format
• Adds proper language labels
• Handles wrap lines settings

Icons & Badges

• Converts Font Awesome icons
• Transforms badge syntax

HTML Entities

• Decodes common entities
• Fixes escaped characters

Variables

• Replaces %varname% with GitBook expressions
• Supports custom variable maps

Migration Reports

After migration, comprehensive reports are generated:

HTML Report (migration-report.html)

• Visual overview of migration
• Statistics and charts
• Clickable file links
• Issue breakdown by file

JSON Reports

• migration-summary.json - Overall statistics
• internal-links-comprehensive.json - Link analysis
• component-details.json - Detailed transformations
• file-issues/ - Individual file issue reports

Report Features

• Link success/failure tracking
• Pattern-based analysis
• Missing file detection
• Page state classification
• Detailed issue descriptions
• Suggested fixes

Document Structure Files

Define your documentation structure in doc_structure.js:

module.exports = [
  {
    title: "GETTING STARTED",
    items: [
      { title: "Introduction", file: "intro.md" },
      { 
        title: "Installation", 
        file: "installation.md",
        items: [
          { title: "Prerequisites", file: "installation/prereqs.md" },
          { title: "Quick Start", file: "installation/quickstart.md" }
        ]
      }
    ]
  },
  {
    title: "API REFERENCE",
    items: [
      { title: "Overview", file: "api/overview.md" }
    ]
  }
];

Auto-Resolution

The package automatically detects the appropriate structure file:

doc_structure.js              # Default
doc_structure_2025.8.js       # Version-specific
doc_structure_troubleshooting.js  # Type-specific
doc_structure_api_v2.js       # Combined

Advanced Usage

Custom Transformation Pipeline

const { migrate, transformers } = require('darkdown-to-markdown');

// Add custom transformer
const customTransformer = (content, filePath) => {
  // Your custom logic
  return content.replace(/custom-pattern/g, 'replacement');
};

// Run migration with custom step
await migrate({
  source: './source',
  destination: './docs',
  customTransformers: [customTransformer]
});

Extending Transformers

const { transformers } = require('darkdown-to-markdown');

// Extend callout transformer
transformers.callouts.addTypeMapping({
  'my-custom-type': 'info'
});

Custom Audit Tracking

const { migrate } = require('darkdown-to-markdown');

const result = await migrate({
  source: './source',
  destination: './docs',
  onProgress: (event) => {
    console.log(`Processing: ${event.file}`);
  },
  onTransform: (type, details) => {
    console.log(`Transformed: ${type}`, details);
  }
});

Troubleshooting

Common Issues

Links not resolving:

• Check doc_structure.js file exists
• Verify file names match exactly
• Review internal-links-comprehensive.json report

Images not downloading:

• Check internet connectivity
• Verify image URLs are accessible
• Use --verbose flag for details

Frontmatter errors:

• Check YAML syntax
• Review migration-summary.json report
• Use YAML validator

Missing files:

• Check migration_map.json
• Review file-issues reports
• Verify source directory structure

Debug Mode

# Enable verbose logging
darkdown-to-markdown migrate ./source -v

# Check validation before migration
darkdown-to-markdown validate ./source

Examples

See the examples/ directory for:

• Basic migration setup
• Custom transformer examples
• Configuration templates
• Report analysis scripts

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

License

MIT © Your Name

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Related Projects

• GitBook
• markdown-it
• remark

---

Made with ❤️ for the documentation community