asciidoctor-html-to-markdown

Convert Asciidoctor HTML to Markdown.

📦 Installation

# Latest beta version
npm install asciidoctor-html-to-markdown@beta
# or
yarn add asciidoctor-html-to-markdown@beta
# or
bun add asciidoctor-html-to-markdown@beta

# Specific beta version
npm install [email protected]

Usage

import { htmlToMarkdown } from "asciidoctor-html-to-markdown";

const markdown = await htmlToMarkdown(asciidoctorHtml);

With Options

import { htmlToMarkdown } from "asciidoctor-html-to-markdown";

const markdown = await htmlToMarkdown(asciidoctorHtml, {
  tocStyle: "none",
  ignoreFirstHeader: false,
  tocMaxDepth: 3,
});

Advanced Usage

import { convert } from "asciidoctor-html-to-markdown";

const result = await convert(html, {
  source: "html",
  target: "markdown",
  convertOptions: {
    tocStyle: "default",
    tocMaxDepth: 2,
    ignoreFirstHeader: true,
    skipHeadersInToc: ["Introduction", "Conclusion"],
  },
});

API

htmlToMarkdown(html: string, options?: ConvertOptions): Promise<string>

Simple conversion function.

convert(html: string, config: ProcessConfig): Promise<ProcessResult>

Full-featured processing with detailed results.

ConvertOptions

type ConvertOptions = {
  // Table of Contents style
  tocStyle?: "default" | "none"; // Default: 'default'

  // Skip first header in TOC and numbering
  ignoreFirstHeader?: boolean; // Default: true

  // Maximum header depth to include in TOC (1=h1 only, 2=h1+h2, etc.)
  tocMaxDepth?: number; // Default: 3

  // Skip specific headers in TOC
  skipHeadersInToc?:
    | number
    | string[]
    | ((content: string, level: number, index: number) => boolean);
};

🐛 Error Handling

The library provides comprehensive error handling:

const result = await convert(malformedHtml, {
  source: "html",
  target: "markdown",
});

if (!result.success) {
  console.error("Conversion failed:", result.errors);
  console.warn("Warnings:", result.warnings);
} else {
  console.log("Success with warnings:", result.warnings);
  console.log("Converted:", result.data);
}

🎨 Table of Contents Styles

Default Style (tocStyle: 'default')

Generates a numbered, clickable table of contents with numbered headers:

# Table of Contents

- [1. Introduction](#1-introduction)
- [2. Getting Started](#2-getting-started)
  - [2.1. Installation](#21-installation)
  - [2.2. Quick Start](#22-quick-start)
- [3. Advanced Usage](#3-advanced-usage)

# 1. Introduction

Content here...

## 1.1. Subsection

More content...

No TOC (tocStyle: 'none')

Generates content without a table of contents:

# Introduction

Content here...

## Subsection

More content...

🚀 CLI Usage

The package includes a command-line interface for converting HTML files to Markdown.

Global Installation

npm install -g asciidoctor-html-to-markdown
# or
yarn global add asciidoctor-html-to-markdown
# or
bun add -g asciidoctor-html-to-markdown

Using with npx

npx asciidoctor-html-to-markdown input.html
npx asciidoctor-html-to-markdown input.html -o output.md
npx asciidoctor-html-to-markdown input.html --toc-style none

CLI Options

Usage: asciidoctor-html-to-markdown <input-file> [options]

Convert HTML files to Markdown format.

Arguments:
  <input-file>              Path to the HTML file to convert

Options:
  -o, --output <file>       Output file path (default: same name with .md extension)
  -q, --quiet              Suppress output messages
  --toc-style <style>      TOC style: default, none (default: default)
  -h, --help               Show this help message
  -v, --version            Show version number

Examples:
  # Global installation
  asciidoctor-html-to-markdown input.html
  asciidoctor-html-to-markdown input.html -o output.md
  asciidoctor-html-to-markdown input.html --toc-style none

Development

git clone https://github.com/janhendry/asciidoctor-html-to-markdown
cd asciidoctor-html-to-markdown
bun install
bun test
bun run build

For detailed local development and testing instructions, see LOCAL-DEVELOPMENT.md.

For deployment and release procedures, see DEPLOYMENT.md.

📄 License

MIT License - see LICENSE file for details.