slamdown 0.5.0

data/readme.md

@@ -0,0 +1,121 @@
+# Slamdown (Ruby Gem)
+
+**Converts potentially-messy HTML to clean Markdown using opinionated, configurable processing rules.**
+
+When an HTML representation of content has been authored poorly, resulting in messy or unsemantic HTML, Slamdown can reduce it to Markdown or Kramdown that reflects editor intent. The processing is opinionated and lossy, with a no-configuration default that suits most situations.
+
+The primary use-case for Slamdown is processing HTML that has been authored in a WYSIWYG editor. These can often accumulate invisible HTML chaos: nested `div`s or `br` instead of `p`, wacky attributes, `i` instead of `em`, etc. A cleaned Markdown/Kramdown representation of this is particularly useful when this content must be used by an SSG like Jekyll.
+
+
+## Convert HTML
+
+Create a document from HTML and render it as Markdown or Kramdown:
+
+```ruby
+require "slamdown"
+
+document = Slamdown::Document.new("<div><h2>Welcome</h2><p>A <b>cleaner</b> document.</p></div>")
+
+document.to_markdown
+# => "# Welcome\n\nA **cleaner** document."
+
+document.to_kramdown
+```
+
+Slamdown cleans common editor output as it converts it. It recognises paragraphs, headings, blockquotes, ordered and unordered lists, definition lists, horizontal rules, links, images, emphasis, strong text, strikethrough, inline and fenced code, and tables. It also recovers semantic emphasis from styled spans where possible, removes comments and processing instructions, normalises whitespace, and drops unsafe link schemes.
+
+Use the full conversion API when you need the output type and conversion diagnostics:
+
+```ruby
+result = Slamdown::Document.convert(document, format: :markdown)
+
+result.output
+result.diagnostics
+```
+
+
+## Options
+
+Pass conversion options as the first argument to `to_markdown` or `to_kramdown`, or as `options:` to `Document.convert`.
+
+```ruby
+document.to_markdown(headings: {start: 1}, entities: :numeric)
+```
+
+| Option | Default | Use it to |
+| --- | --- | --- |
+| `inline` | `false` | Produce inline-friendly output: block elements are flattened and code whitespace is collapsed. |
+| `headings: {start:, compact:}` | `start: 2`, `compact: true` | Set the first heading level (`1`-`6`); compact source heading levels so gaps are removed, or retain their spacing with `compact: false`. |
+| `entities` | `:character` | Render entities as Unicode characters, named entities (`:symbolic`), or numeric entities (`:numeric`). |
+| `html_indent` | `"\t"` | Choose indentation for HTML preserved in the output: `""`, one tab, or one to eight spaces. |
+| `urls: {scheme:, host:, path:, force:}` | `force: :relative` | Rewrite matching link and image URLs. Supply a site scheme, host and/or path; use `force: :relative` for site-relative URLs or `:absolute` (requires scheme and host) for absolute URLs. |
+| `tables: {format:, max_width:}` | `format: :auto`, `max_width: 150` | Use native pipe tables where possible, or `format: :html` to always retain tables as HTML. Set `max_width` to an integer of at least 20, or `nil`, to control pipe-table width before falling back to HTML. |
+| `elements` | `{}` | Change how particular HTML elements are handled and which non-class/id attributes survive. |
+| `classes` | `{}` | Retain matching class names, by element. |
+| `ids` | `{}` | Retain matching IDs, by element. |
+
+The URL options preserve external URLs and query strings/fragments. For example:
+
+```ruby
+document.to_markdown(urls: {scheme: "https", host: "example.com", path: "news", force: :absolute})
+```
+
+
+## Keep or change HTML
+
+By default, Slamdown converts standard structural elements and keeps a small set of semantic HTML elements such as `abbr`, `cite`, `del`, `ins`, `mark`, `sub`, `sup` and `u`. Other unknown elements are unwrapped when they contain useful content, or dropped when they do not. Attributes are dropped unless they are needed by a recognised feature (such as `href`, `src`, `alt`, table spans, or an ordered-list start).
+
+Use `elements` to override this policy. Available actions are:
+
+* `:convert` - convert an element using Slamdown's native rule (only for supported elements).
+* `:preserve` - keep the element as HTML.
+* `:unwrap` - remove the element but keep its contents.
+* `:inline` - keep its contents while flattening block structure.
+* `:drop` - remove the element and its contents.
+
+For example, preserve a `figure` and its `data-*` attribute, while removing all `style` attributes:
+
+```ruby
+options = {
+  elements: {
+    figure: {action: :preserve, attributes: {"data-caption": :preserve}},
+    any: {attributes: {style: :drop}}
+  }
+}
+
+document.to_markdown(options)
+```
+
+Attribute actions are `:preserve` and `:drop`. Use `any` as an element or attribute name to create a catch-all rule; an element-specific rule takes precedence.
+
+Retain only the classes or IDs your output needs. Matchers can be exact strings, regular expressions, arrays of either, or `:any`:
+
+```ruby
+document.to_kramdown(
+  classes: {code: [/\Alanguage-/], table: :any},
+  ids: {h2: ["installation", "usage"]}
+)
+```
+
+
+## Errors and diagnostics
+
+Parsing and conversion errors warn to standard error by default and return an empty or partial result where possible. Choose the behaviour with `errors: :warn` (default), `:silent`, or `:raise`:
+
+```ruby
+document = Slamdown::Document.new(html, errors: :raise)
+result = Slamdown::Document.convert(document, format: :markdown, errors: :raise)
+```
+
+`Document#diagnostics` reports parsing observations. `result.diagnostics` reports conversion observations too, such as adjusted heading levels, removed blank headings, table fallbacks, and recovered editor formatting.
+
+
+## Installation
+
+Add Slamdown to your Gemfile:
+
+```ruby
+gem "slamdown"
+```
+
+Then run `bundle install`.

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: slamdown
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Convincible Media
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+description: Converts potentially-messy HTML to clean Markdown using opinionated,
+  configurable processing rules. Useful for working with HTML that has been authored
+  in a WYSIWYG editor.
+email:
+- development@convincible.media
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- changelog.md
+- lib/slamdown.rb
+- lib/slamdown/conversion.rb
+- lib/slamdown/conversion/configuration.rb
+- lib/slamdown/conversion/configuration_validator.rb
+- lib/slamdown/conversion/converter.rb
+- lib/slamdown/conversion/normalisation.rb
+- lib/slamdown/conversion/normalised_node.rb
+- lib/slamdown/conversion/normaliser.rb
+- lib/slamdown/conversion/normaliser/breaks.rb
+- lib/slamdown/conversion/normaliser/content.rb
+- lib/slamdown/conversion/normaliser/correction_diagnostics.rb
+- lib/slamdown/conversion/normaliser/element_actions.rb
+- lib/slamdown/conversion/normaliser/heading_levels.rb
+- lib/slamdown/conversion/normaliser/inline_semantics.rb
+- lib/slamdown/conversion/normaliser/node_factory.rb
+- lib/slamdown/conversion/normaliser/url_rewriter.rb
+- lib/slamdown/conversion/policy.rb
+- lib/slamdown/conversion/prepared_node.rb
+- lib/slamdown/conversion/preparer.rb
+- lib/slamdown/conversion/renderer.rb
+- lib/slamdown/conversion/rendering/entity_encoder.rb
+- lib/slamdown/conversion/rendering/escaper.rb
+- lib/slamdown/conversion/rendering/html.rb
+- lib/slamdown/conversion/rendering/result.rb
+- lib/slamdown/conversion/rendering/strategy.rb
+- lib/slamdown/conversion/semantic_extractor.rb
+- lib/slamdown/conversion/tables.rb
+- lib/slamdown/diagnostic.rb
+- lib/slamdown/document.rb
+- lib/slamdown/errors.rb
+- lib/slamdown/immutable.rb
+- lib/slamdown/output.rb
+- lib/slamdown/parsing.rb
+- lib/slamdown/parsing/html.rb
+- lib/slamdown/parsing/node.rb
+- lib/slamdown/parsing/parsed_node_adapter.rb
+- lib/slamdown/version.rb
+- readme.md
+homepage: https://github.com/ConvincibleMedia/ruby-gem-slamdown
+licenses:
+- LGPL-3.0-or-later
+metadata:
+  bug_tracker_uri: https://github.com/ConvincibleMedia/ruby-gem-slamdown/issues
+  changelog_uri: https://github.com/ConvincibleMedia/ruby-gem-slamdown/blob/master/changelog.md
+  homepage_uri: https://github.com/ConvincibleMedia/ruby-gem-slamdown
+  source_code_uri: https://github.com/ConvincibleMedia/ruby-gem-slamdown/tree/v0.5.0
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key: 
+specification_version: 4
+summary: Converts potentially-messy HTML to clean Markdown using opinionated, configurable
+  processing rules.
+test_files: []