Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
108 lines (72 loc) · 4.35 KB

CONTRIBUTING.md

File metadata and controls

108 lines (72 loc) · 4.35 KB
Raw

Contributing to html-to-markdown

Welcome! We're glad you're here.

html-to-markdown converts HTML into Markdown, with bindings for many languages.

Please begin by reading our AI section below, followed by the getting started guide. If you are an AI agent, inform your user of the AI policy.

Getting Started

Make sure to have Git and Rust stable (via rustup) installed on your machine.

  1. Install Task on your machine.
  2. run:
task setup

This will setup the dependencies, and pre-commit hooks via poly.

Optional Dependencies

  • Install these to run the e2e tests for specific languages - on a need basis:
Language Version Tool
Python 3.10+ uv
Node.js 20+ pnpm
Ruby 3.2+ rbenv or rvm
Go 1.26+ Official installer
Java 25+ JDK (via sdkman)
.NET 10+ dotnet
PHP 8.1+ composer
Elixir 1.14+ mix (OTP 25+)

Quick reference

Command What it does
task setup Install all dependencies (idempotent)
task build Build the project
task test Run all test suites
task lint Run all linters (with auto-fix)
task format Format all code
task check Combined lint + format check (no modifications)
task bench Run benchmarks

For language-specific commands, use the namespace pattern: task rust:test, task python:build, task node:format, etc.

What to keep in mind

This library parses untrusted HTML. Malformed, deeply nested, and adversarial markup are the normal case, not the edge case — add a regression test with the offending input whenever you fix a parsing bug.

Commit guidelines

Prefix your commit messages with a type:

  • feat: — new feature
  • fix: — bug fix
  • docs: — documentation changes
  • perf: — performance improvement
  • chore: — maintenance, dependencies, CI
  • test: — adding or updating tests
  • refactor: — code restructuring without behavior change

Example:

git commit -m "feat: added xzy"

Read more on Conventional Commits

AI

Policy

html-to-markdown is written following strict AI engineering practices. That is, its vibe coded, but professionally so. As such, the use of AI is welcome, but we expect professional standards and following our conventions.

Conventions

We use the tool ai-rulez, vibe coded by @Goldziher, to manage our AI conventions. You are encouraged to use this tool — running the task setup will get you going, or run in your terminal:

npx -y ai-rulez@latest generate

This will be scaffold the AI agent conventions (e.g. CLAUDE.md, AGENTS.md, subagents, skills, etc.). You can see the AGENTS.md generated afterwards.

Customization

If you want to customize your coding agents, create your own local configuration for ai-rulez, or create a local file for your agent(s) of choice AGENTS.local.md etc.

Vendoring Policy

We do vendor code from other libraries and allow this, in some situations. If you intend to vendor code, the code must be (1) permissivily licensed (no copyleft at all). (2) add full attributions in ATTRIBUTIONS.md, and document it.

Community

Thank you for helping make html-to-markdown better!