prosemirror 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d4941e1033d3813a090427d6d94aac49e2ec017e24f5b1f4a3d8fe4f2600e29
-  data.tar.gz: 04b280abbbe4cb7d997f2c834696faba70e93cf1956a41f9516eeef62fc7ff2a
+  metadata.gz: 9a11c83675790681267f7d5282882f967154892b408d8965e528b1c34d166876
+  data.tar.gz: 14ae8422a61cbe0be055d6ef7590a10981014430978089e14b2805ebf3100be2
 SHA512:
-  metadata.gz: 1641b792c40a58d4b09f158a9ade19d48a85eebc15f7dc1039b913ab056b6c08c0bd4fc27e8809effbdee3e3a0681c1dc8dcf640ca2d2fdeae120314e341a4ce
-  data.tar.gz: cbcabc4bdcf30ad40931501c8f0ab10a84948c0d76d2e31939bcaa2783f17566a539505a897c4992e73817c454ab52e4178a1ef3a8383abf5f7e68dbf34c72ca
+  metadata.gz: 02ac22023a65ba9631752cf6c42b9895cfb4be99acc4d2b1922d0a9742e5d61c7d084455b0c6aec2f0c80400531870113b2ceba519f0a7a4af701de7e192c1f0
+  data.tar.gz: 8adae01f43c5ea57367db4d77605ceb28b4d606829b905440a716c64dc483c82a105898878349bb79f1fd73df4459651e9172d67546ee1d23968fd8cd3538801

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-24
+
+- Import Markdown with `Prosemirror.from_markdown` (or `schema.parse_markdown`). Needs the [`commonmarker`](https://github.com/gjtorikian/commonmarker) gem, which isn't installed with this gem. GitHub Flavored Markdown tables, strikethrough and autolinks are supported, and the schema's parse rules apply, so custom types can match Markdown too. Raw HTML goes through HTML import when the herb gem is installed. YAML front matter is dropped.
+- Import plain text with `Prosemirror.from_text` (or `schema.parse_text`): blank lines separate paragraphs, and other line breaks become hard breaks.
+- HTML, Markdown and text import accept nil and binary strings, and replace invalid UTF-8 with U+FFFD, as browsers do. HTML import raised on invalid UTF-8.
+
+## [0.2.0] - 2026-10-23
+
+- Import HTML with `Prosemirror.from_html` (or `schema.parse_html`), as ProseMirror's `DOMParser` does. Needs the [`herb`](https://herb-tools.dev) gem, which isn't installed with this gem.
+- Node and mark types declare how to recognize them in HTML with `parse_html`, like ProseMirror's parse rules, and attributes with `prop …, parse_html:`. The built-in types have Tiptap's rules.
+- Table cells have an `align` attribute (`left`, `right` or `center`), rendered as a `text-align` style.
+- `Schema.tiptap` sorts marks in Tiptap's order: `code` now comes before `italic`, and `strike` before `underline`.
+- Tiptap's `code` mark can't be combined with other marks, as in Tiptap. `Schema.prosemirror` uses a new `Marks::Basic::Code`, which can.
+- `TYPES.md` documents node and mark types: options, attributes, rendering helpers and parse rules.
+- Custom types can pass Array, Hash or Date attribute values to Phlex outside Rails. Phlex 2.4.1 raised a `NameError` without the `date` library.
+
 ## [0.1.0] - 2026-10-23
 
 - Render ProseMirror and Tiptap JSON to HTML (`to_html`) and text (`to_text`). In Rails, `render doc` works in ERB templates and ViewComponents, and `render doc.to_phlex` in Phlex components.

data/README.md

@@ -1,13 +1,13 @@
 # ProseMirror
 
-Render [ProseMirror](https://prosemirror.net) and [Tiptap](https://tiptap.dev) documents to HTML and text, in Ruby.
+Render [ProseMirror](https://prosemirror.net) and [Tiptap](https://tiptap.dev) documents to HTML and text, and import HTML, Markdown and text into them, in Ruby.
 
 - HTML is built with [Phlex](https://www.phlex.fun) and escaped as it is written.
 - Attributes are typed with [Literal](https://literal.fun).
 - Link and image URLs must use an allowed scheme.
 - No Rails dependency.
 
-This gem replaces [prosemirror_to_html](https://github.com/etaminstudio/prosemirror_to_html) and [html_to_prosemirror](https://github.com/etaminstudio/html_to_prosemirror). HTML and Markdown import are planned: see the [roadmap](ROADMAP.md).
+This gem replaces [prosemirror_to_html](https://github.com/etaminstudio/prosemirror_to_html) and [html_to_prosemirror](https://github.com/etaminstudio/html_to_prosemirror). See the [roadmap](ROADMAP.md) for what comes next.
 
 ## Installation
 
@@ -48,6 +48,57 @@ doc.select { |node| node in { type: :heading, attrs: { level: 1 } } }
 doc.content.first.text_content
 ```
 
+## HTML import
+
+HTML import uses [Herb](https://herb-tools.dev)'s parser, which never raises on malformed HTML. Add it to your Gemfile:
+
+```sh
+bundle add herb
+```
+
+```ruby
+doc = Prosemirror.from_html("<h2>Hello</h2><p>World</p>")
+doc.to_h  # => { "type" => "doc", "content" => [{ "type" => "heading", ... }, ...] }
+```
+
+It works like ProseMirror's `DOMParser`, and for the built-in types gives the same JSON as Tiptap's `generateJSON`, apart from invalid attributes:
+
+- each node and mark type recognizes its elements with its parse rules: `<b>`, `<strong>` and `font-weight: bold` all give `bold`;
+- whitespace is collapsed, except in code blocks;
+- content that doesn't fit where it is gets wrapped or moved: loose text becomes a paragraph, an `<li>` outside a list gets a list;
+- elements without a rule are unwrapped, and `script`, `style` and similar are ignored;
+- entities are decoded, and ERB tags (`<%= … %>`) are kept as text;
+- invalid attributes are fixed and reported, as in [Invalid documents](#invalid-documents).
+
+## Markdown import
+
+Markdown import uses [commonmarker](https://github.com/gjtorikian/commonmarker)'s parser, written in Rust. Add it to your Gemfile:
+
+```sh
+bundle add commonmarker
+```
+
+```ruby
+doc = Prosemirror.from_markdown("## Hello\n\nSome **bold** text.")
+```
+
+It reads GitHub Flavored Markdown: tables, strikethrough and autolinks. Each Markdown node becomes the element commonmarker renders for it, and the schema's parse rules apply as in HTML import, so custom types can match Markdown too: a type that matches `img` also gets Markdown images. For the built-in types, it gives the same JSON as rendering the Markdown to HTML and importing it in Tiptap, except that:
+
+- code blocks lose their final newline, as in prosemirror-markdown;
+- task list items (`- [ ] todo`) stay as list items starting with `[ ] ` or `[x] `.
+
+Raw HTML in Markdown goes through HTML import when the herb gem is installed, and stays as text otherwise.
+
+YAML front matter, between `---` lines at the start, is dropped. Footnotes aren't supported yet: `[^1]: Note` reads as a link definition, as in CommonMark. Markdown nested more than 1,000 levels deep raises `Prosemirror::Error`.
+
+## Text import
+
+```ruby
+doc = Prosemirror.from_text("First line\nsecond line\n\nNew paragraph")
+```
+
+Blank lines separate paragraphs, and other line breaks become hard breaks. Spaces are kept.
+
 ## Schemas
 
 Two schemas are included:
@@ -87,53 +138,17 @@ Prosemirror.schema = Prosemirror::Schema.tiptap.with(ImageBlock)
 
 In `view_template`, `node` is the node being rendered, and `render_content(nodes)` renders any of its descendants.
 
-When an attribute has another name in JSON, declare it with `json:`:
+`parse_html` says which elements become this type when importing HTML, and `prop … parse_html:` how to read an attribute:
 
 ```ruby
-prop :text_align, _String?, json: "textAlign"
-```
-
-See the [cookbook](COOKBOOK.md) for recipes, like skipping empty paragraphs.
-
-### Content expressions
-
-`content` says which children a node can have. It works like a regular expression, with node names or group names instead of characters:
-
-| Expression | Meaning |
-|---|---|
-| `"text*"` | zero or more text nodes |
-| `"inline*"` | zero or more nodes of the `inline` group (text, hard breaks…) |
-| `"block+"` | one or more nodes of the `block` group |
-| `"paragraph block*"` | a paragraph, then zero or more blocks |
-| `"(table_cell \| table_header)*"` | zero or more cells or header cells |
-| `"caption?"` | zero or one caption |
-| `"cell{2}"`, `"cell{1,5}"`, `"cell{2,}"` | exactly two, one to five, two or more cells |
-
-A node type joins a group with `group`, for example `group :block`. A node type without `content` has no children, like an image.
-
-The built-in types use these groups: `block` for paragraphs, headings, lists, tables…, `inline` for text and hard breaks, and `list` for lists.
-
-Today, content expressions are used to find the nodes that contain text, for `to_text`. Rendering doesn't check them. They will also be used by HTML import and validation. See [ProseMirror's guide](https://prosemirror.net/docs/guide/#schema.content_expressions) for details.
-
-### Other options
+class ImageBlock < Prosemirror::NodeType
+  prop :caption, _String?, parse_html: ->(element) { element.query("figcaption")&.text_content }
 
-| Node type option | Meaning |
-|---|---|
-| `group :block, :list` | the groups of the type |
-| `content "inline*"` | the allowed children |
-| `inline` | the node is inline, like text (also implied by `group :inline`) |
-| `marks ""` | the marks allowed inside: names or groups, `"_"` for all, `""` for none |
-| `code` | the node contains code |
-| `whitespace :pre` | keep whitespace when importing HTML (implied by `code`) |
-| `leaf_text "\n"` | the text of a node without children, for `to_text`; also takes a block called with the node |
-| `type_name :image_block` | the type name, when it differs from the class name |
-| `aliases :figure` | other type names accepted on input |
+  parse_html(tag: "figure.image") { |element| {src: element.query("img")&.[]("src")} }
+end
+```
 
-| Mark type option | Meaning |
-|---|---|
-| `spanning false` | render one element per node, instead of one for adjacent nodes with the same mark |
-| `excludes "_"` | the marks it can't be combined with |
-| `group`, `code`, `type_name`, `aliases` | as for node types |
+[Node and mark types](TYPES.md) documents every option: groups, content expressions, allowed marks, attribute names in JSON, rendering helpers, and parse rules. See the [cookbook](COOKBOOK.md) for recipes, like skipping empty paragraphs.
 
 ### Changing built-in types
 
@@ -177,7 +192,15 @@ Prosemirror::Schema.tiptap(
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests, and `rake` to also run [Standard](https://github.com/standardrb/standard). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb` and the changelog, and merge them into main. Then tag the version and push the tag:
+
+```sh
+git tag v0.3.0 && git push origin v0.3.0
+```
+
+The [Push gem](.github/workflows/push_gem.yml) workflow publishes the gem to [rubygems.org](https://rubygems.org) with [trusted publishing](https://guides.rubygems.org/trusted-publishing/), after approval in the `release` environment.
 
 ## Contributing
 

data/ROADMAP.md

@@ -134,26 +134,30 @@ They differ in more than names:
 
 ## Milestones
 
-### 0.1: Rendering
+### 0.1: Rendering (released)
 
 - `Node`, `Mark` and `Document` values, built from a Hash or a JSON string, with a nesting limit.
 - Normalization as in ProseMirror: marks sorted by schema order, adjacent text with the same marks joined, empty text removed.
-- `Schema`, `NodeType` and `MarkType`, with the options of ProseMirror's `NodeSpec` and `MarkSpec`: `content`, `group`, `inline`, `marks`, `whitespace`, `leaf_text`, `excludes`, `spanning`.
+- Attributes a type doesn't declare kept in `unknown_attrs`: never rendered, and given back by `to_h`.
+- `Schema`, `NodeType` and `MarkType`, with the options of ProseMirror's `NodeSpec` and `MarkSpec`: `content`, `group`, `inline`, `marks`, `whitespace`, `leaf_text`, `excludes`, `spanning`. `marks`, `whitespace` and `excludes` are declared, but only take effect with HTML import (0.2) and validation (0.4), as ProseMirror's `fromJSON` doesn't enforce them either.
 - `Schema.tiptap`: `doc`, `paragraph`, `text`, `heading`, `blockquote`, `bullet_list`, `ordered_list`, `list_item`, `code_block`, `hard_break`, `horizontal_rule`, `image`, `table`, `table_row`, `table_header`, `table_cell`. Marks: `link`, `bold`, `italic`, `underline`, `strike`, `code`, `subscript`, `superscript`, `highlight`.
 - `Schema.prosemirror`: exactly the nodes and marks of `prosemirror-schema-basic` and `prosemirror-schema-list`.
 - `to_html`, with one tag for a mark shared by adjacent text (one `<a>` for a link with mixed formatting).
+- `to_phlex` to render in Phlex components, and `render doc` in ERB templates and ViewComponents.
+- `node` and `render_content` in node types, to render parts of a node's content.
 - `to_text`, like Tiptap's `getText`.
-- `case: :camel`, name aliases, allowed URL schemes, `resolve_url`.
-- One JSON test fixture per node and mark.
+- `case: :camel`, name aliases, allowed URL schemes, `resolve_url` (a URL it can't resolve is removed and reported).
+- One JSON test fixture per node and mark, for both schemas.
+- A [cookbook](COOKBOOK.md).
 - Security tests, starting with every issue fixed in `prosemirror_to_html`:
   - unescaped attribute values ([CVE-2025-64501](https://github.com/etaminstudio/prosemirror_to_html/security/advisories/GHSA-52c5-vh7f-26fx));
   - attribute names from the document, like `onmouseover`, and `javascript:` URLs ([GHSA-6gj3-5qf2-wwvv](https://github.com/etaminstudio/prosemirror_to_html/security/advisories/GHSA-6gj3-5qf2-wwvv));
   - a heading `level` like `1><script>`;
   - other URL schemes, hidden schemes (`java\tscript:`), `style` injection, deep nesting.
 
-### 0.2: HTML import
+### 0.2: HTML import (released)
 
-- `Prosemirror.from_html`, built on [Herb](https://herb-tools.dev), which doesn't raise on bad HTML and ships with Rails 8.2.
+- `Prosemirror.from_html`, built on [Herb](https://herb-tools.dev), which doesn't raise on bad HTML.
 - The importer also needs to:
   - decode entities (`&amp;`, `&eacute;`), with the [WHATWG entity list](https://html.spec.whatwg.org/entities.json);
   - keep `<% %>` in content as text;
@@ -165,11 +169,11 @@ They differ in more than names:
 - Old HTML mapped to the schema: `<b>` and `<i>` to `bold` and `italic`, `<strike>` to `strike`, `<tt>` to `code`. `<font>` and `<center>` are unwrapped.
 - Tests: HTML from Tiptap gives the same JSON as Tiptap.
 
-### 0.3: Markdown and text import
+### 0.3: Markdown and text import (released)
 
-- `Prosemirror.from_markdown`, built from [`commonmarker`](https://github.com/gjtorikian/commonmarker)'s syntax tree, without going through HTML (like `prosemirror-markdown`). commonmarker's parser is written in Rust.
-- GitHub Flavored Markdown: tables, strikethrough, autolinks, task lists.
-- Custom node types can define their Markdown mapping.
+- `Prosemirror.from_markdown`, built from [`commonmarker`](https://github.com/gjtorikian/commonmarker)'s syntax tree. commonmarker's parser is written in Rust. Each Markdown node becomes the element commonmarker renders for it, without going through an HTML string, and HTML import's parse rules build the document.
+- GitHub Flavored Markdown: tables, strikethrough, autolinks. Task list items stay as text until task list nodes (0.6).
+- Custom node types match Markdown with their parse rules.
 - Raw HTML in Markdown goes through the HTML importer if Herb is installed.
 - `Prosemirror.from_text`: blank lines make paragraphs, line breaks make hard breaks.
 

data/TYPES.md

@@ -0,0 +1,218 @@
+# Node and mark types
+
+Each node and mark of a document has a type, a Ruby class. A type declares its name, its attributes, what it can contain, how it renders to HTML, and how to recognize it when importing HTML. The options follow ProseMirror's [NodeSpec](https://prosemirror.net/docs/ref/#model.NodeSpec) and [MarkSpec](https://prosemirror.net/docs/ref/#model.MarkSpec).
+
+```ruby
+class Callout < Prosemirror::NodeType
+  group :block
+  content "paragraph+"
+
+  prop :tone, _String?
+
+  parse_html(tag: "aside.callout") { |element| {tone: element["data-tone"]} }
+
+  def view_template(&) = aside(class: "callout", data_tone: @tone, &)
+end
+
+Prosemirror.schema = Prosemirror::Schema.tiptap.with(Callout)
+```
+
+A type is a [Phlex](https://www.phlex.fun) component, and its attributes are [Literal](https://literal.fun) properties. `Schema#with` adds a type to a schema, or replaces the type with the same name.
+
+- [Names](#names)
+- [Node type options](#node-type-options)
+- [Mark type options](#mark-type-options)
+- [Content expressions](#content-expressions)
+- [Attributes](#attributes)
+- [Rendering](#rendering)
+- [Parse rules](#parse-rules)
+- [Markdown](#markdown)
+- [Subclassing built-in types](#subclassing-built-in-types)
+
+## Names
+
+| Option | Meaning |
+|---|---|
+| `type_name :image_block` | The type name. Defaults to the class name in snake_case (`ImageBlock` → `image_block`). |
+| `aliases :figure, :picture` | Other names accepted on input. `Bold` accepts `strong`. |
+
+Type names are snake_case Symbols in Ruby. On input, camelCase works too (`imageBlock`). The schema's `case:` option chooses how they are written in JSON.
+
+## Node type options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `group :block, :list` | none | The groups of the type, used in content expressions and in `marks`. |
+| `content "inline*"` | none: the node is a leaf | The children allowed, as a [content expression](#content-expressions). |
+| `inline` | false | The node is inline, like text. Also implied by `group :inline`. |
+| `marks "bold italic"` | all, in nodes with inline content | The marks allowed inside: names or groups separated by spaces, `"_"` for all, `""` for none. |
+| `code` | false | The node holds code. Implies `whitespace :pre`. |
+| `whitespace :pre` | `:normal` | Keep spaces and newlines when importing HTML. |
+| `leaf_text "\n"` | `""` | The text of a leaf node in `to_text`. Also takes a block, called with the node. |
+| `linebreak_replacement` | false | When importing HTML that keeps whitespace, newlines become nodes of this inline type, like `hard_break`. |
+
+## Mark type options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `group :font` | none | The groups of the type, used in `excludes` and in a node's `marks`. |
+| `excludes "_"` | marks of the same type | The marks this one can't be combined with: names or groups, `"_"` for all. A link excludes other links, and Tiptap's `code` excludes all marks. |
+| `spanning false` | true | Render one element per text node, instead of one for adjacent nodes with the same mark. |
+| `code` | false | The mark holds code, as ProseMirror's `code`. Not used by this gem yet. |
+
+The order of marks in the schema sorts the marks of a node, and nests their elements: the first mark is the outermost element.
+
+## Content expressions
+
+`content` says which children a node can have. It works like a regular expression, with node names or group names instead of characters:
+
+| Expression | Meaning |
+|---|---|
+| `"text*"` | Zero or more text nodes. |
+| `"inline*"` | Zero or more nodes of the `inline` group: text, hard breaks… |
+| `"block+"` | One or more nodes of the `block` group. |
+| `"paragraph block*"` | A paragraph, then zero or more blocks. |
+| `"(table_cell \| table_header)*"` | Zero or more cells or header cells. |
+| `"caption?"` | Zero or one caption. |
+| `"cell{2}"`, `"cell{1,5}"`, `"cell{2,}"` | Exactly two, one to five, two or more cells. |
+
+The built-in types use these groups: `block` for paragraphs, headings, lists, tables…, `inline` for text and hard breaks, and `list` for lists.
+
+HTML import follows content expressions, to wrap content that doesn't fit where it is, or move it up. `to_text` uses them to find the nodes that contain text. Rendering doesn't check them.
+
+## Attributes
+
+Attributes are declared with Literal's `prop`, as keyword properties, and are available as instance variables in `view_template`:
+
+```ruby
+prop :level, _Integer(1..6), default: 1, &Prosemirror::Coerce::INTEGER
+prop :src, _String(length: 1..)
+prop :alt, _String?
+```
+
+- **Type:** a Literal type. A value that doesn't match it is invalid (see [Invalid documents](README.md#invalid-documents)).
+- **Default:** used when the attribute is missing or invalid. Literal needs a frozen value or a Proc: `default: "left".freeze`, or a file with `# frozen_string_literal: true`. An attribute that accepts nil defaults to nil. An attribute without a default is required: without a valid value, the node or mark is removed.
+- **Coercion:** the block converts values before they are checked. `Prosemirror::Coerce::INTEGER` turns `"2"` into `2`.
+
+`prop` takes three more options:
+
+| Option | Meaning |
+|---|---|
+| `json: "textAlign"` | The name in JSON, when it differs from the property name. |
+| `aliases: ["order"]` | Other JSON names accepted on input. |
+| `parse_html: ->(element) { … }` | How to read the attribute from an HTML element, when importing HTML. By default, the HTML attribute with the JSON name is read. |
+
+Attributes that a type doesn't declare are kept in `unknown_attrs`. They are never rendered, and `to_h` gives them back.
+
+## Rendering
+
+A type renders with `view_template`, which yields to render its content. For a mark, the content is the marked text.
+
+```ruby
+def view_template(&) = blockquote(class: "quote", &)
+```
+
+Without `view_template`, the content is rendered without a wrapping element. These methods are also available:
+
+| Method | Returns |
+|---|---|
+| `node` | The node being rendered, a `Prosemirror::Node`. Not available in mark types. |
+| `render_content(nodes)` | Renders any list of nodes, with their marks, for example only some of the node's children. |
+| `safe_url(url)` | The URL after the schema's `resolve_url`, when its scheme is allowed, or nil. Use it for every URL from the document. |
+| `prosemirror_schema` | The schema of the document being rendered. |
+
+Phlex escapes text and attribute values, but doesn't check URLs: pass them through `safe_url`.
+
+## Parse rules
+
+`parse_html` says which elements become this type when importing HTML, like ProseMirror's [parse rules](https://prosemirror.net/docs/ref/#model.ParseRule). A type can have several rules. A type without rules is never created by HTML import.
+
+```ruby
+parse_html tag: "h1", attrs: {level: 1}
+parse_html(tag: "b") { |element| element.style["font-weight"] != "normal" && {} }
+parse_html(style: "font-weight") { |value| value.match?(/bold|[5-9]00/) && {} }
+```
+
+The block is called with the element, or with the value of the style for a style rule. It returns the attributes, `nil` for the defaults, or `false` when the rule doesn't match. A block with two parameters also gets the schema: `{ |element, schema| … }`.
+
+The attributes are built from the rule's `attrs` or block, then from the values each `prop` reads from the element. Values read from the element take precedence, as in Tiptap.
+
+| Option | Meaning |
+|---|---|
+| `tag: "img[src]"` | A CSS selector the element must match. |
+| `style: "font-style=italic"` | For mark types: a CSS property, or a property and value. |
+| `attrs: {level: 1}` | Attributes to give the node or mark. |
+| `priority: 60` | Rules with a higher priority are tried first. Defaults to 50. Rules with the same priority are tried in schema order, mark types first. |
+| `consuming: false` | Let the following rules match the element too, for example to apply several marks. |
+| `context: "list_item/"` | The parents the rule needs. See below. |
+| `ignore: true` | Skip the element and its content. |
+| `skip: true` | Skip the element, but parse its content. |
+| `close_parent: true` | Close the current node: the content that follows goes after it. |
+| `content_element: "figcaption"` | A selector, or a block called with the element, giving the descendant that holds the content. |
+| `get_content: ->(element, schema) { … }` | Returns the nodes to use as content, instead of parsing the element's children. |
+| `preserve_whitespace: true` | Keep spaces. Newlines become `hard_break` nodes where they fit, and spaces otherwise. With `:full`, newlines stay in the text. |
+| `clear_mark: true` | For style rules: remove the marks of this type, as `font-weight: normal` does for bold. Also takes a block called with each mark. |
+
+### Selectors
+
+`tag` takes a list of compound selectors, separated by commas: a type (`p`, `*`), `#id`, `.class`, attribute selectors (`[href]`, `[a=b]`, `[a^=b]`, `[a$=b]`, `[a*=b]`, `[a~=b]`, `[a|=b]`), and `:not(…)`. Combinators like `div > p` aren't supported: use `context`, or check the element in the block.
+
+### Context
+
+`context` matches the nodes the content is being added to, from the innermost one:
+
+| Context | Matches |
+|---|---|
+| `"list_item/"` | Directly in a list item. |
+| `"blockquote//"` | Anywhere inside a blockquote. |
+| `"list_item/paragraph/"` | In a paragraph directly in a list item. |
+| `"blockquote/ \| list_item/"` | One of several contexts. |
+
+Group names work too.
+
+### Elements
+
+The element passed to rules is a `Prosemirror::HTML::Element`, with lowercase names, and attribute values with their character references decoded:
+
+| Method | Returns |
+|---|---|
+| `name` | The tag name, like `"img"`. |
+| `element["src"]` | An attribute value, or nil. |
+| `key?("data-id")` | Whether the attribute is present. |
+| `classes` | The classes, as an Array. |
+| `style` | The declarations of the `style` attribute, as a Hash with lowercase properties: `{"font-weight" => "bold"}`. |
+| `text_content` | The text of the element and its descendants. |
+| `children`, `element_children`, `first_element_child` | The children: elements and texts, elements only, the first element. |
+| `query("img")` | The first descendant matching a selector, or nil. |
+| `matches?("p.lead")` | Whether the element matches a selector. |
+| `parent` | The parent element. |
+
+## Markdown
+
+Markdown import builds the elements commonmarker renders for each Markdown node, and applies the same parse rules. To match Markdown, a type matches these elements:
+
+| Markdown | Element |
+|---|---|
+| Paragraph, heading, blockquote, thematic break | `p`, `h1`…`h6`, `blockquote`, `hr` |
+| Bullet list, ordered list, list item | `ul`, `ol` (with `start` when it isn't 1), `li` |
+| Code block | `pre` holding a `code` with a `language-…` class from the info string |
+| Table | `table`, `tr`, `th` for the first row, `td`, with a `text-align` style for aligned columns |
+| Emphasis, strong, strikethrough, inline code | `em`, `strong`, `s`, `code` |
+| Link, image | `a` with `href` and `title`, `img` with `src`, `alt` and `title` |
+| Hard line break | `br` |
+
+Raw HTML in Markdown goes through HTML import when the herb gem is installed, and stays as text otherwise.
+
+## Subclassing built-in types
+
+A subclass keeps the name, options, attributes and parse rules of its parent, and can change any of them. Register it with `Schema#with`, which replaces the built-in type with the same name:
+
+```ruby
+class Paragraph < Prosemirror::Nodes::Paragraph
+  def view_template(&) = p(class: "text-lg", &)
+end
+
+Prosemirror.schema = Prosemirror::Schema.tiptap.with(Paragraph)
+```
+
+A subclass that declares parse rules replaces the rules of its parent. See the [cookbook](COOKBOOK.md) for more examples.