html-to-markdown-hermes-plugin 3.10.0__py3-none-any.whl

html_to_markdown_hermes_plugin/__init__.py

@@ -0,0 +1,12 @@
+# AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+# Content-Hash: blake3:ad14c165535bf034edc8842cb3a3fbe47dfa5eaa449857fb1081e0a16e49a57f
+# Source-Hash: blake3:1479d0c7507cad8660b86e38c91535d1f1e62aae4e74cf75f1d7ad237f287e1b
+# Schema-Version: v1
+
+"""Hermes Agent plugin package."""
+
+from . import hermes
+from .hermes import register
+
+__version__ = "3.10.0"
+__all__ = ["hermes", "register"]

html_to_markdown_hermes_plugin/hermes.py

@@ -0,0 +1,22 @@
+# AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+# Content-Hash: blake3:37afa818c3d0b98819c2cbb5a6b3bc7aecb66c6e37a8a1ffa2c410efee24b057
+# Source-Hash: blake3:1479d0c7507cad8660b86e38c91535d1f1e62aae4e74cf75f1d7ad237f287e1b
+# Schema-Version: v1
+
+"""Hermes adapter for html-to-markdown.
+
+This generated no-op keeps the plugin loadable without inventing runtime behavior.
+To add Hermes tools, hooks, commands, or other registrations:
+
+1. Create .ai-rulez/hermes/index.py.
+2. Implement register(ctx) in that user-owned source file.
+3. Run ai-rulez generate --plugin.
+
+Project-local Hermes plugins are trusted code. Enable them explicitly with
+HERMES_ENABLE_PROJECT_PLUGINS=true and validate all external input.
+"""
+
+
+def register(ctx):
+    """Register this plugin with Hermes Agent."""
+    del ctx

html_to_markdown_hermes_plugin/plugin.yaml

@@ -0,0 +1,5 @@
+name: "html-to-markdown"
+version: "3.10.0"
+description: "Fast, lossless HTML→Markdown conversion with structured metadata, tables, and document-structure extraction."
+author: "Kreuzberg, Inc."
+kind: "standalone"

html_to_markdown_hermes_plugin/skills/converting-html/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: converting-html
+description: Use when converting HTML to Markdown, Djot, or plain text. Covers output formats, heading and code-block styles, lists, escaping, wrapping, and HTML preprocessing.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:f1b6e5eedc9f268752e34b2c9ad6ecab9ae40c23a8373b1a97838f95a96945d1
+Source-Hash: blake3:1479d0c7507cad8660b86e38c91535d1f1e62aae4e74cf75f1d7ad237f287e1b
+Schema-Version: v1
+-->
+
+# Converting HTML
+
+Use this when the user wants to turn HTML into clean Markdown (or Djot) — a
+saved page, an HTML email body, a fragment, or a string. Conversion is driven by
+**flags** with a positional `FILE` (stdin is the default input when no file is
+given); the only subcommand is `mcp` (run-as-server, see the
+`using-the-mcp-server` skill).
+
+## Basic conversion
+
+```bash
+# File to stdout
+html-to-markdown input.html
+
+# File to a file
+html-to-markdown input.html -o output.md
+
+# From stdin
+cat page.html | html-to-markdown
+echo '<h1>Title</h1><p>Body</p>' | html-to-markdown
+```
+
+The default (no `--json`) prints plain Markdown text. Use `--json` only when you
+need structured metadata/tables (see the `extracting-metadata` and
+`extracting-tables` skills).
+
+## Output format
+
+```bash
+html-to-markdown input.html --output-format markdown   # default
+html-to-markdown input.html --output-format djot        # Djot markup
+html-to-markdown input.html -f djot                      # short form
+```
+
+To get *plain text* (no Markdown syntax), strip tags and treat blocks inline:
+
+```bash
+html-to-markdown input.html --convert-as-inline --strip-tags "script,style"
+```
+
+## Heading and code-block styles
+
+| Flag | Values | Default | Effect |
+| ---- | ------ | ------- | ------ |
+| `--heading-style` | `atx`, `underlined`, `atx-closed` | `atx` | `# h1` vs `h1\n===` vs `# h1 #` |
+| `--code-block-style` | `backticks`, `indented`, `tildes` | `backticks` | Fence style for code blocks |
+| `--code-language` / `-l` | string | `""` | Default language for fenced blocks |
+
+```bash
+html-to-markdown input.html --heading-style underlined --code-block-style tildes
+```
+
+## Lists and text formatting
+
+```bash
+# Bullet characters cycle by nesting depth; indent width 1–8
+html-to-markdown input.html --bullets '*+-' --list-indent-width 2
+
+# Indent with tabs instead of spaces
+html-to-markdown input.html --list-indent-type tabs
+
+# Emphasis symbol and escaping
+html-to-markdown input.html --strong-em-symbol _ --escape-misc
+```
+
+Escaping flags (`--escape-asterisks`, `--escape-underscores`, `--escape-misc`,
+`--escape-ascii`) trade readability for strict CommonMark safety. Use
+`--escape-ascii` only when the output must round-trip through a strict parser.
+
+## Wrapping
+
+```bash
+html-to-markdown input.html --wrap --wrap-width 100   # off by default; 80 if --wrap with no width
+```
+
+## Preprocessing (clean noisy pages)
+
+Strip navigation, ads, and forms before converting — essential for scraped web
+pages:
+
+```bash
+html-to-markdown input.html --preprocess                     # standard preset
+html-to-markdown input.html --preprocess --preset aggressive  # strip more
+html-to-markdown input.html --preprocess --keep-navigation    # keep <nav>
+html-to-markdown input.html --preprocess --keep-forms         # keep <form>
+```
+
+Presets: `minimal`, `standard` (default), `aggressive`. `--preset`,
+`--keep-navigation`, and `--keep-forms` all require `--preprocess`.
+
+## Programmatic equivalents
+
+```python
+from html_to_markdown import convert, ConversionOptions, PreprocessingOptions
+
+result = convert(
+    html,
+    ConversionOptions(
+        heading_style="atx",
+        code_block_style="backticks",
+        wrap=True,
+        wrap_width=100,
+        preprocessing=PreprocessingOptions(enabled=True, preset="aggressive"),
+    ),
+)
+print(result.content)
+```
+
+```rust
+use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle};
+
+let options = ConversionOptions::builder().heading_style(HeadingStyle::Atx).wrap(true).build();
+let result = convert(html, Some(options))?;
+```
+
+See `../html-to-markdown/references/cli-reference.md` for the full flag set and
+`../html-to-markdown/references/configuration.md` for every option default.

html_to_markdown_hermes_plugin/skills/extracting-metadata/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: extracting-metadata
+description: Use when extracting metadata from HTML — title, description, language, Open Graph, JSON-LD / Microdata / RDFa, headers, links, and images. Covers the --json output shape and the --extract-metadata flag.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:92b8609da6942758954515f37da247e2b944e4fa7b5c88f878cfbc58ae3e94cc
+Source-Hash: blake3:1479d0c7507cad8660b86e38c91535d1f1e62aae4e74cf75f1d7ad237f287e1b
+Schema-Version: v1
+-->
+
+# Extracting metadata
+
+Use this when the user wants structured metadata out of HTML rather than (or in
+addition to) the Markdown body — page title, description, language, Open Graph
+tags, structured data, the heading outline, links, or image references.
+
+Metadata lives in `result.metadata` and is surfaced on the CLI through
+`--json`. On the CLI, metadata extraction is **opt-in**: pass
+`--extract-metadata` alongside `--json`, otherwise `result.metadata` comes back
+empty (`document.title` is null, `headers`/`links`/`images`/`structured_data`
+are `[]`). The library `convert()` call extracts metadata by default
+(`extract_metadata=True`) — that default is a property of the API, not the CLI.
+There are no per-field extraction flags: `--extract-metadata` populates all
+sub-fields below at once.
+
+## Get all metadata
+
+```bash
+html-to-markdown --json --extract-metadata input.html | jq '.metadata'
+
+# Extraction-only (skip the Markdown body)
+html-to-markdown --json --extract-metadata --no-content input.html | jq '.metadata'
+```
+
+## Metadata sub-fields
+
+```json
+{
+  "metadata": {
+    "document": { "title": "...", "description": "...", "language": "en", "open_graph": {"title": "..."} },
+    "headers": [ { "level": 1, "text": "Main Heading" } ],
+    "links":   [ { "href": "https://example.com", "link_type": "external" } ],
+    "images":  [ { "src": "photo.jpg", "alt": "A photo", "image_type": "external" } ],
+    "structured_data": [ /* JSON-LD, Microdata, RDFa blocks */ ]
+  }
+}
+```
+
+## Metadata flag
+
+There is one metadata flag: `--extract-metadata`. With `--json` set it populates
+all sub-fields above (`document`, `headers`, `links`, `images`,
+`structured_data`) under `result.metadata` — select what you need with `jq`.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--extract-metadata` | With `--json`: populate `result.metadata`. In plain-text mode (no `--json`): prepend title + meta tags as a YAML frontmatter block (`---`-delimited) at the top of the Markdown output |
+
+```bash
+# Pull just the document-level metadata and the heading outline
+html-to-markdown --json --extract-metadata --no-content input.html \
+  | jq '{title: .metadata.document.title, lang: .metadata.document.language, outline: [.metadata.headers[].text]}'
+```
+
+## Common queries
+
+```bash
+# Title + canonical language
+html-to-markdown --json --extract-metadata input.html | jq '{title: .metadata.document.title, lang: .metadata.document.language}'
+
+# External links only
+html-to-markdown --json --extract-metadata input.html | jq '[.metadata.links[] | select(.link_type == "external") | .href]'
+
+# Open Graph card
+html-to-markdown --json --extract-metadata input.html | jq '.metadata.document.open_graph'
+
+# JSON-LD blocks
+html-to-markdown --json --extract-metadata input.html | jq '.metadata.structured_data'
+```
+
+## Programmatic access
+
+```python
+from html_to_markdown import convert
+
+result = convert(html)
+meta = result.metadata
+print(meta.document.title)        # "My Article"
+print(meta.document.language)     # "en"
+print(meta.headers[0].text)       # "Main Heading"
+print(meta.links[0].link_type)    # "external"
+print(meta.images[0].alt)         # "A photo"
+```
+
+Metadata is available from the single `convert()` call in Python, Rust, Go,
+Ruby, and Elixir; in TypeScript read it off the returned result object. In Rust
+it requires the `metadata` feature (on by default).
+
+See `../html-to-markdown/references/cli-reference.md` (Metadata section) and
+`../html-to-markdown/references/configuration.md` for field details.

html_to_markdown_hermes_plugin/skills/extracting-tables/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: extracting-tables
+description: Use when extracting tabular data from HTML. Covers GFM Markdown tables, the structured tables array (grid cells plus pre-rendered markdown), and HTML line breaks in table cells.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:5597559a9133a3ac5068186a37ec61e7dcdac7881ee4a8077c8efd446e382be1
+Source-Hash: blake3:1479d0c7507cad8660b86e38c91535d1f1e62aae4e74cf75f1d7ad237f287e1b
+Schema-Version: v1
+-->
+
+# Extracting tables
+
+Use this when the user wants tabular data out of HTML — pricing tables, data
+grids, spec sheets. html-to-markdown parses `<table>` elements into two
+surfaces at once: inline GFM Markdown tables in the `content` stream, and a
+structured `tables` array in the JSON output.
+
+## Two surfaces
+
+```bash
+# Inline GFM tables appear in the Markdown body
+html-to-markdown input.html
+
+# Structured table data appears under result.tables (JSON)
+html-to-markdown --json input.html | jq '.tables'
+```
+
+- **Markdown tables in `content`** — `| col | col |` blocks, good for LLM
+  ingestion and human reading.
+- **Structured `tables` array** — each entry has a `markdown` field
+  (pre-rendered) and a `grid` of structured cells (rows × cols). Use this when
+  downstream code needs exact cell access.
+
+Both are populated from the same parse; you do not need a flag to enable table
+parsing.
+
+## Extraction-only
+
+When you only care about tables (not the Markdown body):
+
+```bash
+html-to-markdown --json --no-content input.html | jq '.tables'
+```
+
+## Inspecting tables
+
+```bash
+# How many tables, and the row count of each
+html-to-markdown --json input.html \
+  | jq '.tables | to_entries | map({index: .key, rows: .value.grid.rows, cols: .value.grid.cols})'
+
+# Just the rendered markdown of the first table
+html-to-markdown --json input.html | jq -r '.tables[0].markdown'
+```
+
+## Line breaks in cells
+
+By default `<br>` inside a cell is converted to a space. Keep hard breaks:
+
+```bash
+html-to-markdown input.html --br-in-tables
+```
+
+## Programmatic access
+
+```python
+from html_to_markdown import convert
+
+result = convert(html)
+for table in result.tables:
+    print(table.markdown)            # rendered GFM markdown
+    print(table.grid.cells[0].content)  # first cell (grid is a TableGrid)
+```
+
+```typescript
+import { convert } from "@xberg-io/html-to-markdown";
+
+// Node's convert() returns a ConversionResult object directly.
+const result = convert(html);
+for (const table of result.tables ?? []) {
+  console.log(table.markdown);   // rendered table
+  // table.grid is a TableGrid: { rows, cols, cells: GridCell[] }
+}
+```
+
+## Notes and limits
+
+- **Nested tables** are flattened — the inner table is rendered inline within
+  the parent cell.
+- **Merged / spanning cells** are reconstructed positionally; the span itself
+  is not preserved as separate metadata.
+- **Malformed tables** still parse on a best-effort basis; check `result.warnings`
+  (or `--show-warnings`) for non-fatal issues.
+
+See `../html-to-markdown/references/cli-reference.md` (Tables section) for the
+full flag set.

html_to_markdown_hermes_plugin/skills/fetching-and-converting-urls/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: fetching-and-converting-urls
+description: Use when fetching a live URL and converting it to Markdown. Covers --url, custom user agents, preprocessing for noisy pages, and the --json ConversionResult shape.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:0ec0d1cfab92165c75146dc9c2cd55f3885f8b8e94c2ef4adf24d251263e8697
+Source-Hash: blake3:1479d0c7507cad8660b86e38c91535d1f1e62aae4e74cf75f1d7ad237f287e1b
+Schema-Version: v1
+-->
+
+# Fetching and converting URLs
+
+Use this when the user gives a URL instead of HTML and wants the page as
+Markdown (or its metadata/tables). The CLI fetches the page over HTTP and
+converts it in one step via `--url`. `--url` conflicts with a positional `FILE`.
+
+For crawling *many* pages or following links, use `crawlberg` instead — this
+skill is for a single URL.
+
+## Fetch and convert
+
+```bash
+# Fetch a URL, print Markdown to stdout
+html-to-markdown --url https://example.com
+
+# Save to a file
+html-to-markdown --url https://example.com -o page.md
+
+# Custom User-Agent (default mimics a real browser)
+html-to-markdown --url https://example.com --user-agent "MyBot/1.0"
+```
+
+`--user-agent` requires `--url`.
+
+## Clean noisy pages
+
+Real web pages carry navigation, ads, cookie banners, and forms. Preprocess
+before converting:
+
+```bash
+html-to-markdown --url https://example.com/article --preprocess --preset aggressive
+
+# Keep the nav or forms if the page content lives there
+html-to-markdown --url https://example.com --preprocess --keep-navigation
+```
+
+Presets: `minimal`, `standard` (default), `aggressive`. `--preset` and the
+`--keep-*` flags require `--preprocess`.
+
+## JSON output (ConversionResult)
+
+Add `--json` to get the full structured result instead of plain Markdown:
+
+```bash
+html-to-markdown --url https://example.com --json
+```
+
+```json
+{
+  "content": "# Title\n\nContent\n",
+  "metadata": {
+    "document": { "title": "...", "language": "en" },
+    "headers": [],
+    "links": [],
+    "images": [],
+    "structured_data": []
+  },
+  "tables": [],
+  "images": [],
+  "warnings": []
+}
+```
+
+Useful combinations (all require `--json`):
+
+```bash
+# Page title + outline, no Markdown body
+html-to-markdown --url https://example.com --json --no-content \
+  | jq '{title: .metadata.document.title, headings: [.metadata.headers[].text]}'
+
+# Include the document-structure tree
+html-to-markdown --url https://example.com --json --include-structure | jq '.document'
+
+# Extract inline image data
+html-to-markdown --url https://example.com --json --extract-inline-images | jq '.images | length'
+```
+
+## Surface warnings
+
+```bash
+html-to-markdown --url https://example.com --show-warnings > page.md
+# non-fatal warnings (truncation, malformed markup) go to stderr
+```
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | Success |
+| 1 | Conversion or I/O error (including a failed fetch) |
+| 2 | Invalid arguments |
+
+See `../html-to-markdown/references/cli-reference.md` for the full flag set and
+JSON shape.