@xberg-io/opencode-html-to-markdown 0.1.0

package/.opencode/plugins/html-to-markdown.js

@@ -0,0 +1,202 @@
+import { spawn } from "node:child_process";
+import { tool } from "@opencode-ai/plugin";
+
+const schema = tool.schema;
+
+const headingStyle = schema
+  .enum(["atx", "underlined", "atx-closed"])
+  .optional()
+  .describe("Markdown heading style. Default: atx.");
+
+const codeBlockStyle = schema
+  .enum(["backticks", "indented", "tildes"])
+  .optional()
+  .describe("Code block fence style. Default: backticks.");
+
+const outputFormat = schema
+  .enum(["markdown", "djot"])
+  .optional()
+  .describe("Output markup format. Default: markdown.");
+
+const preset = schema
+  .enum(["minimal", "standard", "aggressive"])
+  .optional()
+  .describe("Preprocessing aggressiveness. Requires `preprocess`. Default: standard.");
+
+function hasValue(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pushOption(args, name, value) {
+  if (hasValue(value)) {
+    args.push(name, String(value));
+  }
+}
+
+function pushFlag(args, name, value) {
+  if (value === true) {
+    args.push(name);
+  }
+}
+
+function runCli(args, context, stdin) {
+  const directory = context?.directory ?? context?.worktree ?? process.cwd();
+
+  return new Promise((resolve, reject) => {
+    const child = spawn("html-to-markdown", args, {
+      cwd: directory,
+      env: process.env,
+      signal: context?.abort,
+      stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+    });
+
+    const stdout = [];
+    const stderr = [];
+
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", (error) => {
+      if (error.code === "ENOENT") {
+        resolve({
+          title: "html-to-markdown CLI not found",
+          output:
+            "Install the html-to-markdown CLI with `brew install xberg-io/tap/html-to-markdown`, or run it via `npx html-to-markdown` / `uvx --from html-to-markdown html-to-markdown`.",
+          metadata: { exitCode: 127, command: "html-to-markdown" },
+        });
+        return;
+      }
+      reject(error);
+    });
+    child.on("close", (exitCode, signal) => {
+      const stdoutText = Buffer.concat(stdout).toString("utf8").trim();
+      const stderrText = Buffer.concat(stderr).toString("utf8").trim();
+      const output = [stdoutText, stderrText && `stderr:\n${stderrText}`]
+        .filter(Boolean)
+        .join("\n\n");
+
+      resolve({
+        title: exitCode === 0 ? "html-to-markdown" : "html-to-markdown failed",
+        output: output || "(no output)",
+        metadata: { exitCode, signal, command: "html-to-markdown" },
+      });
+    });
+
+    if (stdin !== undefined) {
+      child.stdin.write(stdin);
+      child.stdin.end();
+    }
+  });
+}
+
+function styleArgs(args, params) {
+  pushOption(args, "--heading-style", params.heading_style);
+  pushOption(args, "--code-block-style", params.code_block_style);
+  pushOption(args, "--output-format", params.output_format);
+  pushFlag(args, "--preprocess", params.preprocess);
+  pushOption(args, "--preset", params.preset);
+}
+
+export const HtmlToMarkdownPlugin = async () => ({
+  tool: {
+    html_to_markdown_convert: tool({
+      description:
+        "Convert an HTML file or HTML string to Markdown (or Djot) with the html-to-markdown CLI. Provide either `path` or `html`.",
+      args: {
+        path: schema.string().min(1).optional().describe("Path to a local HTML file."),
+        html: schema
+          .string()
+          .min(1)
+          .optional()
+          .describe("Inline HTML to convert (used when `path` is omitted)."),
+        heading_style: headingStyle,
+        code_block_style: codeBlockStyle,
+        output_format: outputFormat,
+        preprocess: schema
+          .boolean()
+          .optional()
+          .describe("Strip navigation, ads, and forms before converting."),
+        preset,
+      },
+      async execute(args, context) {
+        const cliArgs = [];
+        styleArgs(cliArgs, args);
+
+        if (hasValue(args.path)) {
+          cliArgs.push(args.path);
+          return runCli(cliArgs, context);
+        }
+        if (hasValue(args.html)) {
+          return runCli(cliArgs, context, args.html);
+        }
+        throw new Error("Provide either `path` or `html`.");
+      },
+    }),
+    html_to_markdown_fetch_url: tool({
+      description:
+        "Fetch a URL and convert its HTML to Markdown (or Djot) with the html-to-markdown CLI.",
+      args: {
+        url: schema.string().min(1).describe("URL to fetch and convert."),
+        heading_style: headingStyle,
+        code_block_style: codeBlockStyle,
+        output_format: outputFormat,
+        preprocess: schema
+          .boolean()
+          .optional()
+          .describe("Strip navigation, ads, and forms before converting."),
+        preset,
+        user_agent: schema
+          .string()
+          .min(1)
+          .optional()
+          .describe("Custom User-Agent header for the fetch."),
+      },
+      async execute(args, context) {
+        const cliArgs = ["--url", args.url];
+        pushOption(cliArgs, "--user-agent", args.user_agent);
+        styleArgs(cliArgs, args);
+        return runCli(cliArgs, context);
+      },
+    }),
+    html_to_markdown_extract: tool({
+      description:
+        "Extract structured metadata, tables, and (optionally) document structure from HTML as JSON. Returns the full ConversionResult. Provide `path`, `html`, or `url`.",
+      args: {
+        path: schema.string().min(1).optional().describe("Path to a local HTML file."),
+        html: schema
+          .string()
+          .min(1)
+          .optional()
+          .describe("Inline HTML to analyze (used when `path` and `url` are omitted)."),
+        url: schema.string().min(1).optional().describe("URL to fetch and analyze."),
+        include_structure: schema
+          .boolean()
+          .optional()
+          .describe("Include the document structure tree in the JSON output."),
+        no_content: schema
+          .boolean()
+          .optional()
+          .describe("Suppress the Markdown content field — return metadata/tables/images only."),
+      },
+      async execute(args, context) {
+        const cliArgs = ["--json"];
+        pushFlag(cliArgs, "--include-structure", args.include_structure);
+        pushFlag(cliArgs, "--no-content", args.no_content);
+
+        if (hasValue(args.url)) {
+          cliArgs.push("--url", args.url);
+          return runCli(cliArgs, context);
+        }
+        if (hasValue(args.path)) {
+          cliArgs.push(args.path);
+          return runCli(cliArgs, context);
+        }
+        if (hasValue(args.html)) {
+          return runCli(cliArgs, context, args.html);
+        }
+        throw new Error("Provide one of `path`, `html`, or `url`.");
+      },
+    }),
+  },
+});
+
+export default HtmlToMarkdownPlugin;

package/README.md

@@ -0,0 +1,175 @@
+# html-to-markdown
+
+Fast, lossless HTML→Markdown conversion with structured metadata, tables, and document-structure extraction — using the local `html-to-markdown` CLI in your agent.
+
+<!-- TODO: screenshot -->
+
+## Install
+
+### From the marketplace (recommended)
+
+Pending review for official Claude marketplace.
+
+Self-host:
+
+```text
+/plugin marketplace add xberg-io/plugins
+/plugin install html-to-markdown@xberg
+```
+
+### Binary requirement
+
+The bundled MCP launcher (`scripts/mcp-launch.sh`) resolves an
+`html-to-markdown` binary automatically on first run: it reuses one already on
+`PATH`, then tries `npx`/`uvx`, then Homebrew, then a prebuilt download from the
+tool's latest GitHub release. No manual install is required to use the MCP
+server.
+
+To install the CLI yourself:
+
+```bash
+# (Homebrew 6.0+ requires explicit trust for third-party taps)
+brew trust xberg-io/tap
+brew install xberg-io/tap/html-to-markdown
+# or run it without a persistent install (the CLI proxy package self-installs the binary):
+npx @xberg-io/html-to-markdown-cli --help
+uvx --from html-to-markdown-cli html-to-markdown --help
+# or download a prebuilt binary from the latest GitHub release:
+#   https://github.com/xberg-io/html-to-markdown/releases/latest
+# or build from source:
+cargo install html-to-markdown-cli
+```
+
+The skills also cover the language SDKs. Install the one you need:
+
+```bash
+pip install html-to-markdown                  # Python
+npm install @xberg-io/html-to-markdown        # TypeScript / Node.js
+cargo add html-to-markdown-rs                  # Rust
+gem install html-to-markdown                   # Ruby
+```
+
+## Skills shipped
+
+| Skill | Trigger |
+|-------|---------|
+| **html-to-markdown** | Convert HTML to Markdown, Djot, or plain text with structured extraction. Use when writing code that calls html-to-markdown APIs in Rust, Python, TypeScript, Go, Ruby, PHP, Java, C#, Elixir, R, C, or WASM. Covers installation, conversion, configuration, metadata extraction, tables, document structure, and CLI usage. |
+| **converting-html** | Use when converting HTML to Markdown, Djot, or plain text. Covers output formats, heading and code-block styles, escaping, wrapping, and HTML preprocessing. |
+| **extracting-metadata** | 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. |
+| **extracting-tables** | Use when extracting tabular data from HTML. Covers GFM Markdown tables, the structured `tables` array (grid cells + pre-rendered markdown), and `<br>` handling in cells. |
+| **fetching-and-converting-urls** | 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. |
+| **using-the-mcp-server** | Use when converting HTML and extracting metadata through the MCP server's `convert_html`/`extract_metadata` tools instead of the CLI. Covers the tool surface and the auto-installing launcher. |
+
+**Reference materials** (linked from the `html-to-markdown` skill):
+
+| Reference | Content |
+|-----------|---------|
+| **CLI Reference** | All flags, output formats, JSON shape, exit codes |
+| **Configuration Reference** | All 30+ ConversionOptions fields with defaults |
+| **Rust API Reference** | Functions, builder options, feature flags |
+| **Python API Reference** | Functions, dataclasses, type hints |
+| **TypeScript API Reference** | Functions, interfaces, Buffer support |
+| **Other Language Bindings** | Go, Ruby, PHP, Java, C#, Elixir, R, WASM, C FFI |
+
+## MCP server
+
+The plugin auto-registers an MCP server named `html-to-markdown`, launched via
+`scripts/mcp-launch.sh` (which execs `html-to-markdown mcp`). It exposes two
+tools — `convert_html` (HTML string → Markdown/Djot/plain text, or the full
+`ConversionResult` JSON with `json: true`) and `extract_metadata` (structured
+metadata from an HTML string) — so the agent can convert HTML directly without
+shelling out to the CLI. The launcher auto-installs a
+binary on first run (override with
+`HTML_TO_MARKDOWN_LAUNCHER=auto|npx|uvx|brew|download`). The `mcp` subcommand
+ships in a recent release of the tool; an older binary on `PATH` may need an
+upgrade to expose it. See the **using-the-mcp-server** skill for details.
+
+## CLI / SDK usage
+
+The conversion CLI takes **flags only** — `FILE` is positional; omit it (or use `-`) to read HTML from stdin. (The one subcommand is `mcp`, which starts the MCP server.)
+
+```bash
+html-to-markdown input.html                    # convert file to stdout
+html-to-markdown input.html -o output.md       # convert to a file
+cat page.html | html-to-markdown               # read from stdin
+html-to-markdown --url https://example.com     # fetch and convert a URL
+html-to-markdown --json input.html             # full ConversionResult as JSON
+```
+
+The same single entry point exists across the SDKs — `convert()` returns a structured `ConversionResult` (`content`, `metadata`, `tables`, `images`, `warnings`):
+
+```python
+from html_to_markdown import convert
+
+result = convert("<h1>Hello</h1><p>World</p>")
+print(result.content)   # # Hello\n\nWorld
+print(result.metadata)  # title, links, headers, …
+```
+
+```typescript
+import { convert } from "@xberg-io/html-to-markdown";
+
+// Node's convert() returns a ConversionResult object directly.
+const result = convert("<h1>Hello</h1><p>World</p>");
+console.log(result.content);  // # Hello\n\nWorld
+```
+
+Prefer the CLI for one-shot conversions and shell pipelines; prefer the SDKs when embedding conversion in application code.
+
+## Configuration
+
+All conversion behavior is controlled by CLI flags (or the matching `ConversionOptions` fields in the SDKs):
+
+| Flag | Values | Default | Purpose |
+|------|--------|---------|---------|
+| `--output-format` / `-f` | `markdown`, `djot`, `plain` | `markdown` | Output markup format. |
+| `--heading-style` | `atx`, `underlined`, `atx-closed` | `atx` | Heading rendering. |
+| `--code-block-style` | `backticks`, `indented`, `tildes` | `backticks` | Code fence style. |
+| `--preprocess` / `-p` | flag | off | Strip nav, ads, forms before converting. |
+| `--preset` | `minimal`, `standard`, `aggressive` | `standard` | Preprocessing aggressiveness (needs `--preprocess`). |
+| `--wrap` / `-w`, `--wrap-width` | flag, 20–500 | off, `80` | Text wrapping. |
+| `--json` | flag | off | Emit the full `ConversionResult` JSON. |
+| `--include-structure` | flag | off | Add the document-structure tree (needs `--json`). |
+| `--no-content` | flag | off | Extraction-only — skip the Markdown text. |
+
+See `skills/html-to-markdown/references/configuration.md` for the full 30+ option table and `skills/html-to-markdown/references/cli-reference.md` for every flag.
+
+## Examples
+
+Convert an HTML file to Markdown:
+
+```text
+html-to-markdown article.html -o article.md
+```
+
+Scrape a page with aggressive preprocessing:
+
+```text
+html-to-markdown --url https://example.com/blog --preprocess --preset aggressive
+```
+
+Extract metadata and tables only (no Markdown body):
+
+```text
+html-to-markdown --json --no-content page.html | jq '{title: .metadata.document.title, tables: (.tables | length)}'
+```
+
+Convert with Djot output and underlined headings:
+
+```text
+html-to-markdown input.html --output-format djot --heading-style underlined
+```
+
+## Versioning
+
+The plugin version tracks the marketplace `VERSION` file. See [CHANGELOG.md](../../CHANGELOG.md) for release notes.
+
+## License
+
+MIT. The skill content references the upstream [html-to-markdown](https://github.com/xberg-io/html-to-markdown) repository.
+
+## See also
+
+- **Marketplace**: [xberg-io/plugins](https://github.com/xberg-io/plugins)
+- **Upstream**: [xberg-io/html-to-markdown](https://github.com/xberg-io/html-to-markdown)
+- **Sibling plugins**: [xberg](../xberg/README.md), [crawlberg](../crawlberg/README.md)

package/assets/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <rect width="256" height="256" rx="48" fill="#2E2D36"/>
+  <path d="M64 56 L152 56 L196 100 L196 196 C196 200.4 192.4 204 188 204 L64 204 C59.6 204 56 200.4 56 196 L56 64 C56 59.6 59.6 56 64 56 Z" fill="#58FBDA"/>
+  <path d="M152 56 L152 92 C152 96.4 155.6 100 160 100 L196 100 Z" fill="#2E2D36"/>
+  <path d="M84 168 L84 124 L100 144 L116 124 L116 168" fill="none" stroke="#2E2D36" stroke-width="12" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M150 124 L150 168 M150 168 L134 150 M150 168 L166 150" fill="none" stroke="#2E2D36" stroke-width="12" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,26 @@
+<svg width="800" height="800" viewBox="0 0 800 800" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="400" cy="400" r="313.839" fill="#58FBDA" stroke="#2E2D36" stroke-width="7.67819"/>
+<path d="M469.155 481.996L497.619 509.815L517.95 513.534L529.157 523.7" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M428.146 495.931V565.751L454.576 592.876V615.587" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M333.878 482.343L310.522 509.468L289.15 512.543L271.199 525.733" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M404.521 155.839C498.389 155.839 574.411 231.075 574.411 323.792C574.411 416.509 498.389 491.744 404.521 491.744C310.653 491.744 234.631 416.509 234.631 323.792C234.631 231.075 310.653 155.839 404.521 155.839Z" fill="#79FFE6" stroke="#2E2D36" stroke-width="7.67819"/>
+<path d="M401.021 218.481C450.893 218.481 491.275 258.538 491.275 307.892C491.275 357.246 450.893 397.303 401.021 397.303C351.149 397.303 310.767 357.246 310.767 307.892C310.767 258.538 351.149 218.481 401.021 218.481Z" fill="white" stroke="#2E2D36" stroke-width="6.14255"/>
+<circle cx="231.379" cy="476.492" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<circle cx="256.471" cy="535.8" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<circle cx="300.109" cy="582.413" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<circle cx="401.071" cy="643.307" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<circle cx="457.998" cy="631.009" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<path d="M457.304 487.798V535.601L489.139 569.123" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<circle cx="499.354" cy="582.413" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<circle cx="542.695" cy="535.006" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<circle cx="562.332" cy="476.393" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+<path d="M303.381 465.483L289.993 476.988H248.834" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M351.532 489.484V531.188L312.555 569.817" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M371.863 494.889V569.123L345.78 596.942V615.24" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M401.368 498.311V625.753" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<path d="M496.925 465.731L505.057 473.566H545.422" stroke="#2E2D36" stroke-width="7.67819" stroke-linecap="round"/>
+<ellipse cx="401.021" cy="307.892" rx="51.671" ry="53.0099" fill="#2E2D36"/>
+<ellipse cx="411.286" cy="294.106" rx="18.5956" ry="19.0915" fill="white"/>
+<ellipse cx="428.493" cy="322.471" rx="8.43002" ry="8.67796" fill="white"/>
+<circle cx="344.143" cy="632.299" r="14.8269" fill="white" stroke="#2E2D36" stroke-width="4.60691"/>
+</svg>

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xberg-io/opencode-html-to-markdown",
+  "version": "0.1.0",
+  "description": "OpenCode tools for HTML→Markdown conversion with the html-to-markdown CLI.",
+  "keywords": [
+    "conversion",
+    "html",
+    "html-to-markdown",
+    "markdown",
+    "opencode"
+  ],
+  "homepage": "https://github.com/xberg-io/plugins/tree/main/plugins/html-to-markdown",
+  "bugs": {
+    "url": "https://github.com/xberg-io/plugins/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xberg-io/plugins.git",
+    "directory": "plugins/html-to-markdown"
+  },
+  "files": [
+    ".opencode/",
+    "assets/",
+    "README.md"
+  ],
+  "type": "module",
+  "main": ".opencode/plugins/html-to-markdown.js",
+  "exports": {
+    ".": "./.opencode/plugins/html-to-markdown.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.17.8"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  }
+}