BridgetownHtmlToMarkdown

A Bridgetown plugin that automatically generates a .md Markdown file for every rendered .html file during the site build process, powered by the fast Rust-backed html-to-markdown gem.

• Converts rendered HTML pages to Markdown on :site, :post_write.
• Generates dual paths for nested pages (e.g., categories/index.html creates both categories/index.md and categories.md).
• Strips interactive dialogs/lightboxes while allowing selective preservation.
• Extracts SVG accessibility labels (aria-label, alt, <title>) and strips noisy inline SVG vector data.
• Cleans spacing around inline formatting and adjacent navigation links.
• Supports custom regex/string replacements prior to Markdown conversion.
• Registers text/markdown; charset=utf-8 MIME type for Rack-based Bridgetown servers to prevent character encoding issues in browsers.

Add the gem to your Bridgetown application:

bundle add bridgetown-html-to-markdown

Or add it directly to your Gemfile:

gem "bridgetown-html-to-markdown", "~> 0.1.0"

In your Bridgetown site's config/initializers.rb:

init :"bridgetown-html-to-markdown"

You can pass options directly to init:

init :"bridgetown-html-to-markdown",
  # Custom string or regex replacements before markdown conversion
  replacements: {
    /<section class="interactive-tool".*?<\/section>/m => "<p>Please see our catalog for details.</p>"
  },

  # Glob patterns of files to exclude (default includes 404.html, 500.html, search verification files)
  exclude_files: ["google*.html", "404.html", "500.html", "BingSiteAuth.xml"],

  # Glob patterns of files to include even if they match exclude_files
  include_files: ["404.html"],

  # Strip <dialog> elements (default: true)
  exclude_dialogs: true,

  # Preserve specific dialogs by CSS selector (id or class)
  preserve_dialog_selectors: ["#contact-dialog"],

  # Extract aria-label, alt, or <title> from SVGs and strip svg markup (default: true)
  extract_svg_labels: true,

  # Clean spacing between adjacent inline tags and links (default: true)
  clean_spacing: true

Alternatively, options can be set in config/bridgetown.config.yml:

html_to_markdown:
  exclude_dialogs: true
  clean_spacing: true

After checking out the repository, run bin/setup to install dependencies. Then run bundle exec rake to run tests and code style checks.

The gem is available as open source under the terms of the MIT License.