@opositatest/markdown-text-editor 1.4.1 → 1.4.5

package/README.md

@@ -34,22 +34,69 @@ The editor currently focuses on text-first rich content that serializes cleanly
 - Inline styles: bold, italic, underline, strikethrough, and inline code
 - Display math blocks written in LaTeX
 
-Indented / nested blocks are **not** part of the supported surface: `Tab` never indents (see [Tab key](#tab-key)).
+Indented / nested blocks are **not** part of the supported surface, with one exception: a list item nested under
+another list item is a nested list in Markdown, so `Tab` creates it (see [Tab key](#tab-key)). The formatting
+toolbar still offers no *Anidar bloque* / *Desanidar bloque* action.
 
 ### Tab key
 
 `Tab` behaves like it does in any other form control: it moves focus to the next focusable element of the
-host page (`Shift-Tab` moves to the previous one), so it never indents a block or uses the browser's focus as a
-trap. `Escape` still blurs the editor.
+host page (`Shift-Tab` moves to the previous one), so a paragraph, a heading or a quote never indents, and the
+editor never uses the browser's focus as a trap. `Escape` still blurs the editor.
 
-The only exceptions are BlockNote's own behaviours *inside* a block:
+The exceptions are BlockNote's own behaviours *inside* a block:
 
+- **Lists** (bullet, numbered, checklist, toggle): `Tab` on the second and later items nests the item under the
+  previous one, and `Shift-Tab` lifts a nested item back out. A nested list is the one kind of indentation
+  Markdown can express, so it round-trips as `* parent` / `  * child`. The **first** item of a list cannot nest
+  (there is nothing above it to nest into), so `Tab` there leaves the editor - there is always a way out of the
+  field with the keyboard.
 - **Code blocks**: `Tab` inserts two spaces. `Shift-Tab` leaves the editor.
 - **Tables**: `Tab` / `Shift-Tab` move between cells. At the first/last cell they leave the editor instead of
   indenting the table.
 
-Markdown that already contains nested lists (pasted content or a document saved before this rule) is still
-parsed and re-exported unchanged, but indentation can no longer be created from the keyboard.
+The nest/un-nest buttons BlockNote ships in the formatting toolbar are filtered out (`EXCLUDED_ITEM_KEYS` in
+`src/components/app-block-note-view/app-formatting-toolbar.tsx`, pinned by `app-formatting-toolbar.test.tsx`):
+they indent whatever block is selected - a paragraph, a list under a paragraph, a paragraph under a list item -
+and Markdown reads all of those lines back as *siblings*, so the nesting the user saw would disappear on the
+next save. Only `Tab` inside a list nests, and only when the result is still a list. That filter matches on the
+upstream item `key` (`nestBlockButton` / `unnestBlockButton`), so an upstream rename would silently bring the
+buttons back rather than fail loudly.
+
+Markdown that already contains nested lists is parsed and re-exported unchanged, and a paragraph nested under a
+list item is currently flattened out of it when the document is saved again.
+
+### Numbered apartados and literal numbers
+
+A number you type is **never** turned into an automatic list, so the number you wrote is the number that is
+saved. Typing `1. `, `2. `, `3.ª`… at the start of a line just writes that text, exactly like the BOE does, and
+apartados that are cited elsewhere by number are never renumbered:
+
+- `1. No será preciso…` and `3. Tampoco será preciso…` stay two lines of text, aligned the same way, even when
+the second one skips a number.
+- Markdown cannot express "1, 3": inside a list only the first item's number is kept and the editor paints every
+  other number from the item's position, which is why an automatic list cannot hold a number you wrote.
+
+This is also why paragraph text that starts with a block marker is escaped when the document is saved
+(`3. No será preciso` is stored as `3\. No será preciso`). Without the escape, that line would come back as a
+numbered list item, so the number would stop being text and start being renumbered. The escape renders exactly
+the same in any Markdown renderer.
+
+To create an actual numbered list, use the slash menu (`/lista numerada`), the block type selector or
+`Ctrl/⌘+Shift+7`; it keeps its own positional numbering, and Markdown documents that already contain lists are
+loaded as lists.
+
+### Pasting
+
+Pasted content is taken at face value: the `text/html` flavour when the source provides it, plain text otherwise.
+It is never *guessed* to be Markdown, because the plain text of a legal document is full of lines starting with
+`1. `, and parsing it as Markdown turned the apartados into an automatic list that then renumbered them (`1.`,
+`3.` came back as `1.`, `2.`).
+
+- `Ctrl/⌘+V` from a web page keeps the HTML structure — headings, bold, links — with the numbers as text.
+- `Ctrl/⌘+Shift+V` (paste without formatting) inserts the text literally, which is what the **Quitar formato**
+  button suggests when the source formatting is not wanted.
+- Explicit Markdown still works: `text/markdown` on the clipboard, and the editor's own `pasteMarkdown()`.
 
 ### Math / LaTeX blocks
 
@@ -121,6 +168,8 @@ Selecting text opens the formatting toolbar. Its **Quitar formato** action conve
 text blocks to paragraphs and removes inline styles, colors, code formatting, and links in one
 undoable operation. Non-text blocks such as images, tables, and formulas are left unchanged.
 
+The toolbar never offers nesting/un-nesting (see [Tab key](#tab-key)); text alignment is still available.
+
 The action tooltip also shows the browser shortcut for pasting without source formatting:
 `Ctrl/⌘ + Shift + V`.