@willwang-io/react-djot 0.1.5 → 0.1.6

package/README.md

@@ -41,7 +41,7 @@ export function Example() {
 ### `<Djot />`
 
 ```tsx
-import { Djot } from "react-djot";
+import { Djot, compileDjot } from "react-djot";
 
 <Djot
   children={"# Title"}
@@ -51,15 +51,22 @@ import { Djot } from "react-djot";
     }
   }
 />;
+
+const ast = compileDjot("# Precompiled");
+<Djot ast={ast} />;
 ```
 
 Props:
 
 - `children?: string | null | undefined`
   - Djot source text to parse and render.
+- `ast?: DjotNode`
+  - Precompiled Djot AST to render directly (bypasses parsing).
 - `components?: DjotComponents`
   - Optional map of node-tag keys to React components.
 
+`children` and `ast` are mutually exclusive. Use one or the other.
+
 ### `components` overrides
 
 The override pattern mirrors `react-markdown`: provide a component per node
@@ -113,25 +120,38 @@ export function Example() {
 - `subscript`
 - `insert`
 - `delete`
+- `span`
 - `footnote_reference`
 - `footnote`
 - `endnotes`
 - `double_quoted`
 - `single_quoted`
 - `smart_punctuation`
+- `symb`
 - `inline_math`
 - `display_math`
 - `code`
 - `verbatim`
 - `code_block`
+- `raw_block`
+- `raw_inline`
+- `url`
+- `email`
 - `link`
 - `image`
 - `bullet_list`
 - `ordered_list`
 - `list_item`
+- `definition_list`
+- `definition_list_item`
+- `term`
+- `definition`
+- `task_list`
+- `task_list_item`
 - `blockquote` and `block_quote`
 - `thematic_break`
 - `str`
+- `non_breaking_space`
 - `soft_break` and `softbreak`
 - `hard_break` and `hardbreak`
 
@@ -141,6 +161,110 @@ export function Example() {
 - Walks the AST recursively and creates React elements directly
 - Does not use `dangerouslySetInnerHTML`
 
+## Raw HTML
+
+Djot raw blocks and raw inlines are supported:
+
+- Block: `~~~=html ... ~~~`
+- Inline: `` `...`{=html} ``
+
+Only `html` format is rendered by default. Other formats are ignored unless you
+provide a `components.raw_block` or `components.raw_inline` override.
+
+## Autolinks
+
+Autolink nodes are supported:
+
+- `<https://pandoc.org/lua-filters>` -> `<a href="https://pandoc.org/lua-filters">...`
+- `<me@example.com>` -> `<a href="mailto:me@example.com">...`
+
+## Reference Links and Images
+
+Reference-style links and images resolve against document references:
+
+```djot
+[foo][bar]
+![logo][img]
+
+[bar]: https://example.com
+[img]: /logo.png
+```
+
+## Attributes
+
+Inline and block attributes are propagated to default rendered elements.
+Parser-generated `autoAttributes` are also applied, and explicit attributes
+take precedence on conflicts.
+
+For nodes with built-in classes (for example `task_list`, `inline_math`,
+`display_math`), user classes are merged with default classes.
+
+## Symbols
+
+Djot symbols (`:alias:`) render literally by default. You can provide a
+`components.symb` override to map aliases to emojis or any custom output.
+
+## Task Lists
+
+A bullet list item starting with `[ ]` (unchecked) or `[x]`/`[X]` (checked)
+is a task list item:
+
+```djot
+- [ ] unchecked item
+- [x] checked item
+```
+
+By default, task list items render as `<li>` elements with a disabled
+`<input type="checkbox">` prepended to the content. Use the `task_list` and
+`task_list_item` override keys to customise this rendering:
+
+```tsx
+const components: DjotComponents = {
+  task_list_item: ({ checkbox, children }) => (
+    <li data-checked={checkbox === "checked"}>{children}</li>
+  )
+};
+```
+
+Tight task lists (no blank lines between items) render item text inline with
+the checkbox. Loose task lists preserve paragraph wrappers (`<p>...</p>`)
+inside each item.
+
+Styling note: browsers apply default list markers to `<ul>/<li>`. To match
+Djot playground output (checkboxes without bullet dots), reset task-list
+styles in your app CSS:
+
+```css
+.task-list {
+  list-style: none;
+  padding-left: 0;
+}
+
+.task-list li {
+  list-style: none;
+}
+
+.task-list input[type="checkbox"] {
+  margin-right: 0.45rem;
+}
+```
+
+## Definition Lists
+
+Definition list items are supported and render to semantic `<dl>/<dt>/<dd>`
+elements:
+
+```djot
+: orange
+
+  A citrus fruit.
+```
+
+## Non-breaking Spaces
+
+An escaped space (`\ `) is parsed as `non_breaking_space` and renders as a
+non-breaking space character.
+
 ## React Server Components
 
 `<Djot />` has no hooks in the main render path, so it can be used in Server