cfxmark 0.1.3__tar.gz

cfxmark-0.1.3/.gitignore

@@ -0,0 +1,60 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+
+# uv
+.venv/
+.python-version
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Local dev artifacts
+.omc/
+.omx/
+/tmp/
+*.log
+
+# Secrets (never commit)
+.secrets/
+*.pem
+*.key
+
+# Real-world corpus — may contain internal company content (Jira keys,
+# attachments, drawio diagrams). Tests skip if absent. Place private
+# samples here on your dev machine; never commit them.
+/tests/corpus/*.cfx
+/tests/corpus/*.json
+/tests/corpus/private/
+/tests/to_md/

cfxmark-0.1.3/CHANGELOG.md

@@ -0,0 +1,211 @@
+# Changelog
+
+All notable changes to **cfxmark** will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.3] — 2026-04-07
+
+### Changed
+
+- `render_cfx` now returns a third element — a ``warnings`` list —
+  alongside ``(xhtml, attachments)``. Any ``::: jira`` / ``::: toc``
+  (or other parameter-only directive) whose body is silently dropped
+  by its handler now surfaces a human-readable warning via
+  ``ConversionResult.warnings`` so callers can correct their
+  Markdown instead of discovering the drop on Confluence.
+
+## [0.1.2] — 2026-04-07
+
+### Fixed
+
+- Attachment enumeration now strips CDATA sections before scanning
+  for `<ri:attachment>`, so a Confluence ``code`` macro documenting
+  storage XML no longer leaks phantom filenames into
+  `result.attachments`. `resolve_assets(mode="sidecar")` applies the
+  same CDATA strip on its opaque-block fallback.
+- `to_cfx` now emits only the **basename** of a local-image path in
+  `<ri:attachment ri:filename="...">` (Confluence stores attachments
+  in a flat per-page namespace). `result.attachments` still reports
+  the caller's original path — including any directory prefix — so
+  the caller knows where to read the bytes from on disk.
+
+## [0.1.1] — 2026-04-07
+
+### Fixed
+
+- `ConversionResult.attachments` now enumerates **every**
+  `ri:attachment` reference in the output XHTML, including those
+  trapped inside Grade III opaque blocks (e.g. `<ac:image>` inside
+  `<pre><code>`). Previously only Grade I/II native `<ac:image>`
+  references were reported, so callers silently missed attachments
+  they needed to upload. `to_md` also populates `attachments` now
+  (previously always empty).
+- `resolve_assets(mode="sidecar")` downloads opaque-block attachments
+  into `asset_dir` as a fallback, keeping the sidecar directory a
+  complete asset set regardless of how the image was preserved.
+- `to_cfx` no longer crashes with `IndexError` when user-typed
+  Markdown contains a literal `` `CFXMARK_OPAQUE-N-CFXMARK` `` /
+  `` `CFXMARK_DIRECTIVE-N-CFXMARK` `` token whose index has no
+  matching capture — the region falls back to plain inline code.
+
+### Docs
+
+- README custom-macro example uses a valid `AdmonitionHandler` flavour
+  (`info`/`note`/`warning`/`tip`); the previous `"danger"` example
+  raised `ValueError`.
+- README docs/SPEC/OPAQUE/LICENSE links rewritten as absolute GitHub
+  URLs so they resolve correctly when rendered on PyPI.
+- `docs/SPEC.md` no longer claims `<ac:layout>` wrappers become opaque
+  blocks; cfxmark flattens them transparently.
+
+### Packaging
+
+- `pyproject.toml` switched to PEP 639 license metadata
+  (`license = "MIT"` + `license-files = ["LICENSE"]`); the redundant
+  `License :: OSI Approved :: MIT License` classifier was removed.
+- Added `Documentation` and `Changelog` entries to `[project.urls]`
+  for the PyPI sidebar.
+
+## [0.1.0] — 2026-04-07
+
+### Added
+
+#### Conversion API
+
+- `cfxmark.to_cfx(markdown)` — Markdown → Confluence Storage Format XHTML.
+- `cfxmark.to_md(xhtml)` — Confluence Storage Format XHTML → Markdown.
+- Both return a `ConversionResult` carrying `xhtml` / `markdown`,
+  `attachments` (local file references for the caller to upload),
+  `warnings`, and the intermediate AST.
+
+#### Native (grade I) constructs — lossless round-trip
+
+- ATX headings `h1`–`h6`.
+- Paragraphs, hard breaks, soft breaks, HTML entities.
+- Inline emphasis: `**bold**`, `*italic*`, `` `code` ``, `~~strike~~`,
+  links, images.
+- Lists: bullet, ordered, deeply nested, mixed paragraph + nested-list
+  list items.
+- Block quotes, horizontal rules.
+- Code fences with language tags (mapped to Confluence's `code` macro).
+- GFM tables with **`colspan` / `rowspan`** support via the
+  MultiMarkdown `<` / `^` continuation cell convention. Multi-paragraph
+  cells flatten to inline content joined by `<br>` tags.
+
+#### Directive (grade II) macros
+
+Pluggable `MacroRegistry`. Default registry covers:
+
+- `info`, `note`, `warning`, `tip` admonition panels.
+- `jira` issue references (single + JQL query forms).
+- `expand` collapsible sections.
+- `toc` table of contents.
+
+Each is rendered as a pandoc-style fenced div in Markdown:
+
+```
+::: info
+body
+:::
+```
+
+#### Opaque (grade III) preservation
+
+The signature feature: any Confluence construct cfxmark does not know
+how to represent in Markdown is preserved **byte-for-byte**, including
+the `ac:macro-id` UUID that gives Confluence its macro identity.
+
+- **Block opaque**: HTML-comment sentinel + `cfx-storage` fenced code
+  block. SHA-256 fingerprint in the sentinel ID prevents accidental
+  collision with user-typed content.
+- **Inline opaque**: short `[label](cfx:op-XXXXXXXX)` Markdown link
+  with the XML payload stored in a `cfxmark:payloads` sidecar at the
+  bottom of the document. The label is auto-derived from the
+  underlying element type (`@user-…`, `jira:PROJ-1`, `cfx:status`, …).
+- **Header notice**: a single-line `<!-- cfxmark:notice ... -->` HTML
+  comment is injected at the top of any document containing opaque or
+  directive constructs, telling humans and AI agents not to delete the
+  markers.
+
+#### Image asset workflow
+
+- `to_md` automatically tags every local-attachment image with a
+  `<!-- cfxmark:asset src="..." -->` metadata marker carrying the
+  original Confluence filename.
+- New `cfxmark.resolve_assets(md, fetcher, mode="sidecar"|"inline")`
+  function reads the markers, calls a caller-provided `fetcher` to
+  download the bytes, and either saves them to a sidecar directory
+  (with relative path links) or embeds them as `data:` URIs.
+- Markers are preserved across resolution so the round trip back to
+  CFX always recovers the original Confluence filename — even after
+  the visible link target has been rewritten to a sidecar path.
+- Image dimensions encoded in the URL fragment as
+  `#cfxmark:w=300,h=200` for round-trip preservation.
+
+#### Canonicalization (`canonicalize_cfx`)
+
+A deep XML normalization pass that lets two semantically equivalent
+Confluence storage fragments compare equal:
+
+- Strips volatile attributes (`ac:macro-id`, `ac:local-id`,
+  `ri:version-at-save`, `ac:schema-version`, `ac:thumbnail`,
+  `ac:border`, `ac:align`).
+- Strips Confluence-editor data attributes
+  (`data-uuid`, `data-highlight-colour`, …).
+- Removes purely cosmetic CSS (default text colour, `text-align`,
+  `width` / `height` on table family elements, `font-weight`,
+  `padding`, `margin`, `list-style-type`, `vertical-align`, …).
+- Removes Confluence-editor class names
+  (`wrapped`, `fixed-width`, `auto-cursor-target`, `code-line`,
+  `has-list-bullet`, `internal-link`, `confluenceTd`, …).
+- Unwraps decorative `<span>` and structural `<div>` wrappers
+  (including the `content-wrapper` div Confluence emits inside table
+  cells).
+- Promotes header rows to `<thead>`, splits `<h*>` containing `<br/>`,
+  flattens singleton paragraphs inside `<li>`, drops empty paragraphs
+  and trailing breaks, normalizes `<pre><code>` to the structured
+  `code` macro form, removes cosmetic code parameters
+  (`linenumbers`, `theme`, `firstline`, …).
+
+#### Security hardening
+
+- Rejects any input containing `<!DOCTYPE>` or `<!ENTITY>` to block
+  XXE and billion-laughs attacks.
+- lxml parser configured with `no_network=True`, `load_dtd=False`,
+  `huge_tree=False`.
+- Opaque sentinels carry a SHA-256 fingerprint of their body — a user
+  who types the literal sentinel sequence in their Markdown is **not**
+  silently turned into an opaque block; the verification fails and
+  the region falls back to plain text.
+
+#### Tooling
+
+- `py.typed` marker for PEP 561 consumers.
+- `pyproject.toml` configured for `uv` and `hatchling`.
+- mypy clean (non-strict for v0.1; strict planned for v0.2).
+- ruff clean.
+- 65 tests:
+  - 39 unit tests (per-construct + edge cases)
+  - 7 image asset tests
+  - 8 security regression tests
+  - 1 corpus golden-file test (skipped if no private corpus available)
+  - 1 Hypothesis property-based round-trip test (100 random documents)
+- Verified against 9 production Confluence pages totalling ~290 KB
+  of XHTML — all round-trip with byte-identical canonical form.
+
+### Known limitations
+
+- **HTML comments in Markdown** are dropped with a warning, with one
+  exception: cfxmark's own opaque / asset / header markers are
+  preserved. Confluence does not preserve HTML comments either, so
+  this matches Confluence's own behaviour.
+- **`drawio`, `plantuml`** and other rich diagram macros are
+  passed through as opaque blocks (preserved losslessly but not
+  rendered in Markdown).
+- **`MacroHandler` protocol leaks lxml**. Custom macro handlers
+  currently receive and return `lxml.etree._Element` objects. A thin
+  adapter is planned for v0.2.
+- **`<th scope="...">`, `<td title="...">`** attributes are stripped
+  during canonicalization since Markdown cannot preserve them.

cfxmark-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eunsan Jo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cfxmark-0.1.3/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: cfxmark
+Version: 0.1.3
+Summary: Bidirectional Markdown <-> Confluence Storage XHTML converter with lossless opaque preservation.
+Project-URL: Homepage, https://github.com/eunsanMountain/cfxmark
+Project-URL: Repository, https://github.com/eunsanMountain/cfxmark
+Project-URL: Issues, https://github.com/eunsanMountain/cfxmark/issues
+Project-URL: Documentation, https://github.com/eunsanMountain/cfxmark/blob/main/docs/SPEC.md
+Project-URL: Changelog, https://github.com/eunsanMountain/cfxmark/blob/main/CHANGELOG.md
+Author: Eunsan Jo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bidirectional,confluence,converter,markdown,round-trip,storage-format,xhtml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: lxml>=5.0
+Requires-Dist: mistletoe>=1.3
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: lxml-stubs>=0.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cfxmark
+
+**Bidirectional Markdown ↔ Confluence Storage XHTML converter** —
+with lossless opaque preservation for everything cfxmark doesn't
+explicitly know how to convert.
+
+```python
+import cfxmark
+
+# Markdown → Confluence storage XHTML
+result = cfxmark.to_cfx(markdown_text)
+result.xhtml          # str    — ready for Confluence REST PUT
+result.attachments    # tuple  — local file refs the caller should upload
+result.warnings       # tuple  — human-readable conversion warnings
+
+# Confluence storage XHTML → Markdown
+result = cfxmark.to_md(xhtml_text)
+result.markdown       # str    — canonical markdown
+result.warnings       # tuple
+```
+
+`ConversionResult` is the same dataclass for both directions —
+`xhtml` is populated for `to_cfx`, `markdown` for `to_md`.
+
+## Why another converter?
+
+Two existing projects inspired this one — [`md2cf`][md2cf] and
+[`md2conf`][md2conf] — but both are **one-directional** (md → cf) and
+neither preserves unknown macros across a round trip. `cfxmark` fills
+both gaps:
+
+1. **Bidirectional.** `to_md(to_cfx(m))` is byte-identical to
+   `canonicalize(m)` for every construct in the supported subset.
+2. **Opaque preservation.** Confluence content cfxmark doesn't
+   understand (custom plugins, drawio diagrams, exotic table cells)
+   round-trips byte-for-byte, **including the `ac:macro-id` UUID**.
+   Confluence treats the round-tripped macro as the same instance, so
+   comments, attachments, and permissions stay attached.
+3. **Pure text-in / text-out.** No Confluence API, no network, no
+   attachment upload. The caller owns REST I/O. (See "Image assets"
+   below for the helper function that lets the caller plug in
+   network-bound logic without bloating cfxmark.)
+
+[md2cf]: https://github.com/iamjackg/md2cf
+[md2conf]: https://github.com/hunyadi/md2conf
+
+## Install
+
+```bash
+# With uv (recommended):
+uv add cfxmark
+
+# With pip:
+pip install cfxmark
+```
+
+cfxmark depends on `lxml` and `mistletoe`. Python 3.10+.
+
+## The contract
+
+cfxmark grades every Confluence construct into one of three buckets:
+
+| Grade | Description | Behaviour |
+|---|---|---|
+| **I — Native** | Standard CommonMark / GFM (headings, lists, tables, code fences, links, images, blockquote, hr, inline emphasis) | Lossless round-trip after canonicalization. |
+| **II — Directive** | Confluence macros with a known Markdown directive mapping (`info`, `note`, `warning`, `tip`, `jira`, `expand`, `toc`) | Lossless after canonicalization. Pluggable via `MacroRegistry`. |
+| **III — Opaque** | Everything else | Captured byte-for-byte through cfxmark's opaque-block / inline-opaque mechanism. **Never dropped, never rewritten.** |
+
+See [`docs/SPEC.md`](https://github.com/eunsanMountain/cfxmark/blob/main/docs/SPEC.md)
+for the full mapping table and
+[`docs/OPAQUE.md`](https://github.com/eunsanMountain/cfxmark/blob/main/docs/OPAQUE.md)
+for the opaque-block format.
+
+## Usage
+
+### Round-trip a Confluence page through Markdown
+
+```python
+import cfxmark
+
+# Whatever fetched the page (REST API call, exported XML file, …)
+xhtml = my_confluence_client.get_storage_format(page_id)
+
+# Convert to Markdown
+md_result = cfxmark.to_md(xhtml)
+markdown = md_result.markdown
+
+# … user edits the Markdown …
+
+# Convert back to Confluence storage XHTML
+cfx_result = cfxmark.to_cfx(markdown)
+my_confluence_client.update_page(page_id, cfx_result.xhtml)
+
+# Optionally upload any newly referenced local images
+for filename in cfx_result.attachments:
+    my_confluence_client.upload_attachment(page_id, filename)
+```
+
+### Image assets
+
+When you convert a Confluence page that references uploaded
+attachments, the resulting Markdown looks like this:
+
+```markdown
+![](image-3.png#cfxmark:w=700)<!-- cfxmark:asset src="image-3.png" -->
+```
+
+The image link still points at the original Confluence filename
+(broken in any local Markdown viewer until you fetch the bytes), and
+the `<!-- cfxmark:asset -->` HTML comment carries enough metadata for
+a follow-up step to fetch and embed.
+
+`cfxmark.resolve_assets` is that follow-up step. You provide a
+fetcher callback that returns bytes for one filename at a time, and
+choose between two output strategies:
+
+```python
+import cfxmark
+from pathlib import Path
+
+def fetcher(filename: str) -> bytes:
+    # Whatever you use to download from Confluence:
+    return my_confluence_client.download_attachment(page_id, filename)
+
+# Strategy A — sidecar directory (recommended for git-tracked docs).
+# Saves bytes to ./assets/ and rewrites links to relative paths.
+md = cfxmark.resolve_assets(
+    md_result.markdown,
+    fetcher,
+    mode="sidecar",
+    asset_dir="docs/page-42/assets",
+    md_path="docs/page-42.md",
+)
+Path("docs/page-42.md").write_text(md)
+# docs/page-42/assets/image-3.png exists
+# md link: ![](assets/image-3.png#cfxmark:w=700)<!-- cfxmark:asset src="image-3.png" -->
+
+# Strategy B — inline data URIs (single self-contained file).
+md = cfxmark.resolve_assets(md_result.markdown, fetcher, mode="inline")
+# md link: ![](data:image/png;base64,iVBORw0K...)<!-- cfxmark:asset src="image-3.png" -->
+```
+
+The asset markers are **preserved** through both strategies, so
+`resolve_assets` is idempotent and a subsequent `to_cfx` call always
+recovers the original Confluence filename — even if the visible link
+target has been rewritten to a sidecar path or a data URI.
+
+### Mermaid diagrams
+
+cfxmark maps Markdown's `` ```mermaid `` fenced code block to
+Confluence's `code` macro with `language=mermaid`. If your Confluence
+instance has a Mermaid plugin installed (e.g. *Mermaid Diagrams for
+Confluence*) it will render the diagram automatically; otherwise the
+content is shown as a syntax-highlighted code block.
+
+```markdown
+​```mermaid
+graph LR
+  A --> B --> C
+​```
+```
+
+### Inline opaque references
+
+Inline elements that have no native Markdown form — Confluence user
+mentions, inline Jira issue macros, custom widget invocations, … —
+become a short Markdown link with a `cfx:op-...` URL:
+
+```markdown
+Contact the purchaser ([@user-2c9402cc](cfx:op-4fab0f8d))
+```
+
+The `[label]` is auto-derived from the underlying element type
+(`@user-…`, `jira:PROJ-1`, `cfx:status`, …) and the `op-XXXXXXXX` ID
+is a SHA-256 prefix of the original XML payload. The full XML lives
+in a `cfxmark:payloads` sidecar at the bottom of the same Markdown
+file:
+
+```markdown
+<!-- cfxmark:payloads -->
+<!-- op-4fab0f8d
+<ac:link><ri:user ri:userkey="2c9402cc83d4bcc40183d976ef730001"/></ac:link>
+-->
+<!-- /cfxmark:payloads -->
+```
+
+The SHA-256 fingerprint means a user who **types** that exact link
+syntax in their own Markdown is not silently re-interpreted as an
+opaque payload — the verification fails and the region falls back to
+ordinary text.
+
+### Block opaque blocks
+
+Block-level Confluence content cfxmark doesn't know how to convert
+(e.g. drawio diagrams, plantuml, complex tables) is wrapped in a
+fenced code block with sentinel comments:
+
+````markdown
+<!-- cfxmark:opaque id="op-1188e2b4" -->
+```cfx-storage
+<ac:structured-macro ac:name="drawio" ac:macro-id="...">
+  <ac:parameter ac:name="diagramName">flow</ac:parameter>
+  ...
+</ac:structured-macro>
+```
+<!-- /cfxmark:opaque -->
+````
+
+Editors render this as a clearly visible code block — a "do not
+touch" signal for human readers. The Markdown parser detects the
+sentinels first and round-trips the contents byte-for-byte, including
+the original `ac:macro-id` UUID that Confluence uses to identify
+macro instances.
+
+### Header notice
+
+When a converted Markdown document contains any opaque or directive
+markers, cfxmark prepends a single-line HTML comment explaining the
+conventions to humans and AI agents:
+
+```markdown
+<!-- cfxmark:notice Converted from Confluence storage format. Inline
+[label](cfx:op-XXXXXXXX) references preserve Confluence content that
+has no native Markdown form; the raw XML for each lives in the
+cfxmark:payloads sidecar at the bottom of this file. Do not edit
+those references or the sidecar — tampering invalidates a SHA-256
+fingerprint and the round trip falls back to plain text. -->
+```
+
+The comment is invisible in any Markdown viewer.
+
+### Custom macros
+
+Promote a Confluence macro from "opaque" to "directive" by registering
+a custom handler:
+
+```python
+import cfxmark
+from cfxmark.macros import MacroRegistry
+from cfxmark.macros.builtins import AdmonitionHandler
+
+# Start from the default registry and add your own.
+my_registry = cfxmark.default_registry.copy()
+# Built-in AdmonitionHandler accepts one of: "info", "note", "warning", "tip".
+# To promote a previously-opaque macro, write a small MacroHandler subclass —
+# see cfxmark/macros/builtins/admonition.py for a complete example.
+my_registry.register(AdmonitionHandler("warning"))
+
+result = cfxmark.to_md(xhtml, macros=my_registry)
+```
+
+Implementing a `MacroHandler` from scratch requires a small amount
+of lxml knowledge — see `cfxmark/macros/builtins/admonition.py` for
+a complete example. A higher-level handler API that hides lxml is
+planned for v0.2.
+
+### Canonicalization helpers
+
+Two Confluence storage fragments are "the same" only after a deep
+normalization pass that strips volatile attributes, editor noise,
+and rendering hints. Use `canonicalize_cfx` to compare two snapshots:
+
+```python
+import cfxmark
+
+c1 = cfxmark.canonicalize_cfx(original_xhtml)
+c2 = cfxmark.canonicalize_cfx(round_tripped_xhtml)
+assert c1 == c2  # passes for any document in the supported subset
+```
+
+`canonicalize_cfx` is the same function the test suite uses to
+verify byte-identical round trips against real Confluence pages.
+
+## Security
+
+cfxmark hardens its XML parser against XXE and billion-laughs attacks:
+
+- Inputs containing `<!DOCTYPE>` or `<!ENTITY>` declarations are
+  rejected before lxml ever sees them.
+- The lxml parser is configured with `no_network=True`,
+  `load_dtd=False`, and `huge_tree=False`.
+- Opaque-block sentinels are SHA-256 verified — accidental sentinel
+  syntax in user-typed Markdown does **not** become a real opaque
+  block.
+
+If you find a security issue, please open a GitHub issue.
+
+## Development
+
+```bash
+git clone https://github.com/eunsanMountain/cfxmark
+cd cfxmark
+uv sync --all-extras
+
+# Run all tests
+uv run pytest
+
+# Type-check
+uv run mypy src/
+
+# Lint
+uv run ruff check .
+
+# Build
+uv build
+```
+
+The corpus tests look for `.cfx` files in `tests/corpus/` (gitignored
+to keep your own private samples out of version control). Drop your
+own Confluence storage XHTML there and they will be exercised by
+`pytest tests/test_corpus.py`.
+
+## License
+
+MIT. See [`LICENSE`](https://github.com/eunsanMountain/cfxmark/blob/main/LICENSE).