Output Formats

This guide helps you choose the right format among plain text, Markdown, and JSON outputs.

Format Comparison

Feature	Plain Text	Markdown	JSON
Readability	High	High	Low (machine-friendly)
Structure Preservation	None	Headings/lists/links/images	Full metadata
Image Handling	Removed		ImageInfo list
Link Handling	Text only	[text](url)	LinkInfo list
Table Support	None	Markdown tables	Raw data
Use Cases	Search indexing/text analysis	Blogs/docs/readers	API transport/data storage

Plain Text

The lightest output format, keeping only text content and removing all HTML tags and formatting.

text, err := html.ExtractText(data)
if err != nil {
    log.Fatal(err)
}
fmt.Println(text)

Use Cases

• Building search indexes
• Text analysis and NLP processing
• Generating summaries and previews
• Word count and reading time statistics

Characteristics

• Image alt text is removed; link visible text is retained (only the URL and Markdown syntax are stripped)
• Line breaks preserved between headings and paragraphs
• List content displayed as plain text
• Tables are rendered per TableFormat (Markdown tables by default)

Markdown

Preserves document structure while maintaining readability. Ideal for content migration and reading scenarios.

// Option 1: Package-level function
md, err := html.ExtractToMarkdown(data)

// Option 2: Use Processor
p, _ := html.New()
defer p.Close()
md2, err := p.ExtractToMarkdown(data)

Output Example

Input HTML:

<article>
    <h1>Getting Started with Go</h1>
    <p>Go is a compiled language.</p>
    <img src="gopher.png" alt="Gopher" />
    <a href="https://go.dev">Go Official Site</a>
</article>

Output Markdown:

Getting Started with Go

Go is a compiled language.

![Gopher](gopher.png)
[Go Official Site](https://go.dev)

Format Options

Markdown format is controlled by two config fields:

cfg := html.DefaultConfig()
cfg.InlineImageFormat = "markdown"  // "none" | "markdown" | "html" | "placeholder"
cfg.InlineLinkFormat = "markdown"   // "none" | "markdown" | "html"

Format Value	Image Output (InlineImageFormat)	Link Output (InlineLinkFormat)
none	Removed	Text only
markdown		[text](url)
html	<img src="..." alt="...">	<a href="...">text</a>
placeholder	[IMAGE:N]	- (not supported)

Use MarkdownConfig()

The MarkdownConfig() preset already sets image and link formats to markdown. Just use it directly without manual configuration.

Placeholder Format

placeholder only applies to InlineImageFormat, inserting [IMAGE:N] placeholders in text. InlineLinkFormat does not support this value — only none, markdown, html.

Use Cases

• Content migration to Markdown blogs/static sites
• Email body generation
• Document format conversion
• RSS / Newsletter content generation

JSON

Structured output preserving complete metadata. Ideal for inter-program transmission and persistent storage.

jsonBytes, err := html.ExtractToJSON(data)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(jsonBytes))

Output Structure

{
  "text": "Getting Started with Go\n\nGo is a compiled language.\n\nGo Official Site",
  "title": "Getting Started with Go",
  "images": [
    {"url": "gopher.png", "alt": "Gopher", "title": "", "width": "", "height": "", "is_decorative": false, "position": 1}
  ],
  "links": [
    {"url": "https://go.dev", "text": "Go Official Site", "title": "", "is_external": true, "is_nofollow": false, "position": 1}
  ],
  "processing_time_ms": 2,
  "word_count": 12,
  "reading_time_ms": 3600
}

Time Fields

In JSON output, ProcessingTime and ReadingTime are automatically converted to milliseconds (processing_time_ms, reading_time_ms) for frontend and API consumption.

Use Cases

• API response data
• Database storage
• Microservice communication
• Frontend application integration

Extracting All Formats from Files

Each format supports file reading:

// Plain text
text, err := html.ExtractTextFromFile("page.html")

// Markdown
md, err := html.ExtractToMarkdownFromFile("page.html")

// JSON
jsonBytes, err := html.ExtractToJSONFromFile("page.html")

Context Variants

All format functions have ExtractWithContext variants supporting timeout and cancellation:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

md, err := html.ExtractToMarkdownWithContext(ctx, data)

Decision Guide

Need machine consumption?── yes ──→ JSON
        │
        no
        │
Need format preservation?── yes ──→ Markdown
        │
        no
        │
        └──→ Plain Text

Next Steps

• API Reference: Output Formats - Complete API signatures
• Link Extraction & Grouping - Extract page resource links
• Configuration - All configuration options