inkmd 0.1.0__tar.gz

inkmd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dylan Moir
+
+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.

inkmd-0.1.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: inkmd
+Version: 0.1.0
+Summary: Pure-Python markdown to PDF compiler. Zero system dependencies. Deterministic.
+Author: Dylan Moir
+License: MIT License
+        
+        Copyright (c) 2026 Dylan Moir
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/eagredev/inkmd
+Project-URL: Repository, https://github.com/eagredev/inkmd
+Project-URL: Issues, https://github.com/eagredev/inkmd/issues
+Keywords: markdown,pdf,compiler,deterministic,zero-dependencies
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Printing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# inkmd
+
+**Markdown to PDF, pure Python, zero dependencies. MIT-licensed. Deterministic.**
+
+```sh
+pip install inkmd
+inkmd in.md -o out.pdf
+```
+
+That's the whole install. No system packages, no fonts to install, no Chrome binary, no `apt-get`. Works the same on macOS, Linux, Windows, Alpine, AWS Lambda, a locked-down CI runner, or a Steam Deck.
+
+<p align="center">
+  <img src="docs/images/hero-sample.png" alt="A quarterly report rendered by inkmd, showing headings, a styled paragraph with strikethrough, a blockquote, a right-aligned table with tinted header, a bulleted list, and a fenced Python code block with a grey background." width="640">
+  <br>
+  <em><a href="examples/hero-sample.md">examples/hero-sample.md</a> rendered through inkmd: headings, inline styles, strikethrough, blockquote, GFM table, list, fenced code, autolinked URL and email all in one page.</em>
+  <br>
+  <em>See also <a href="examples/inkmd-brief.md">examples/inkmd-brief.md</a>, a two-page project brief written in inkmd-renderable markdown.</em>
+</p>
+
+## What you get
+
+- **A single pure-Python wheel.** No native extensions, no system libraries. Installs in under a second.
+- **Faithful CommonMark plus the parts of GFM people actually use:** tables, autolinks, strikethrough, fenced code with language tags. The [supported features](#supported-markdown) section has the full matrix.
+- **PDFs that look right.** Real AFM-driven kerning emitted via TJ arrays, clickable links, tinted code-block backgrounds, blockquote rules that stack for nested quotes, table alignment, headings that breathe.
+- **Byte-identical output for the same input.** No clocks, no random IDs. Useful for version control, signed PDFs, audit trails, reproducible CI.
+- **Two layers of API:** a CLI and a `compile()` / `render_file()` library function. The whole public surface is two functions.
+
+## Why this exists
+
+Markdown to PDF is a solved problem in theory and a minefield in practice. Every other tool brings heavy system dependencies that don't survive the trip into an Alpine container, a Lambda function, or a Windows machine without admin rights.
+
+| Tool | What goes wrong |
+|------|-----------------|
+| **wkhtmltopdf** | Deprecated since 2023. Unpatched CVEs. |
+| **Chrome headless / Puppeteer** | 200MB+ install. 5 to 15s cold-start latency. |
+| **WeasyPrint** | Needs Pango, cairo, GObject (350 to 550MB of system packages). Breaks on Alpine and Windows. |
+| **Pandoc + LaTeX** | 3GB texlive install. |
+| **PyMuPDF-based tools** | Don't build on Alpine musl. |
+| **`borb`** | AGPL, so unusable in closed-source or commercial projects without a paid licence. |
+
+`inkmd` runs anywhere Python runs. It's the markdown-to-PDF compiler you'd write yourself with a free weekend if you didn't want to take a dependency on a browser.
+
+## Use cases
+
+- **CI documentation pipelines.** Compile READMEs, release notes, or changelogs to PDF as a build artefact, in a stripped-down container, without `apt-get`.
+- **Agent-generated documents.** LLM agents that need to deliver a PDF (CVs, reports, summaries) can call `inkmd.compile()` directly. No subprocess, no shell-out, no Chrome.
+- **Reproducible audit trails.** Hash the markdown, hash the PDF, and the same input gives the same output bytes. Useful for compliance, signed reports, version-controlled docs.
+- **Serverless rendering.** Lambda plus zero system dependencies equals a PDF endpoint that cold-starts in well under a second.
+- **Restricted environments.** Locked-down CI runners, embedded hardware, anywhere installing a 200MB browser isn't an option.
+
+## Status
+
+**v0.1, feature-complete, MIT-licensed.** 501 tests across 24 files. Stdlib-only, Python 3.9+. Byte-deterministic output. The [torture test](examples/torture-test.md) covers everything `inkmd` can render.
+
+## Install
+
+From PyPI:
+
+```sh
+pip install inkmd
+```
+
+Or grab the single-file zipapp (no `pip` install required). Each tagged release attaches an `inkmd.pyz` of around 300 KB that you can drop anywhere Python 3.9+ is available:
+
+```sh
+curl -L -o inkmd.pyz https://github.com/eagredev/inkmd/releases/latest/download/inkmd.pyz
+python inkmd.pyz in.md -o out.pdf
+```
+
+Or build it yourself from a checkout:
+
+```sh
+python scripts/build_zipapp.py    # produces dist/inkmd.pyz
+```
+
+## Usage
+
+### CLI
+
+```sh
+inkmd in.md -o out.pdf              # file in, file out
+inkmd in.md > out.pdf               # file in, stdout out
+inkmd < in.md > out.pdf             # stdin in, stdout out
+inkmd in.md -o out.pdf --page-size A4 --family times
+inkmd in.md -o out.pdf --no-autolinks
+inkmd --version
+```
+
+### Library
+
+```python
+import inkmd
+
+# Compile markdown text to PDF bytes
+pdf_bytes = inkmd.compile(md_text)
+
+# Or convert files directly
+inkmd.render_file("in.md", "out.pdf")
+
+# Options (same on both functions)
+pdf_bytes = inkmd.compile(
+    md_text,
+    page_size="A4",          # or "letter" (default)
+    family="times",          # or "helvetica" (default)
+    autolinks=False,         # opt out of GFM bare-URL/email detection
+)
+```
+
+The public API is intentionally narrow: two functions, no classes to instantiate, no state to manage. The CLI is a thin argparse wrapper around `compile()`.
+
+## Supported markdown
+
+### CommonMark
+
+| Feature | inkmd |
+|---------|:---:|
+| Paragraphs with line wrapping | Yes |
+| ATX headings (`#` to `######`) | Yes |
+| Setext headings (`===` / `---`) | Yes |
+| Ordered lists, arbitrary `start` | Yes |
+| Unordered lists (`-` / `*` / `+`) | Yes |
+| Nested lists, mixed marker types | Yes |
+| Tight vs. loose list detection | Yes |
+| Blockquotes | Yes |
+| Nested and multi-paragraph blockquotes | Yes |
+| Blockquotes wrapping any block type | Yes |
+| Fenced code blocks | Yes |
+| Code block language tag (info string) | Yes |
+| Indented code blocks | Yes |
+| Code spans (`` `code` ``) | Yes |
+| Emphasis (`*`, `_`) | Yes |
+| Strong emphasis (`**`, `__`) | Yes |
+| Triple `***` becomes nested italic-bold | Yes |
+| Rule of 3 plus intraword-underscore | Yes |
+| Backslash escapes | Yes |
+| Thematic breaks | Yes |
+| Inline links `[text](url)` | Yes |
+| Inline link titles | Yes |
+| Angle-bracket autolinks `<url>` | Yes |
+| Images `![](...)` | v0.2 |
+| Reference-style links | v0.2 |
+| HTML blocks / inline HTML | not planned |
+
+### GFM extensions
+
+| Feature | inkmd |
+|---------|:---:|
+| Pipe tables | Yes |
+| Table column alignments | Yes |
+| Bare URL autolinks (`https://...`, `www....`) | Yes |
+| Bare host autolinks (`host.tld/path`) | Yes |
+| Email autolinks | Yes |
+| Strikethrough `~~text~~` | Yes |
+| Task lists `- [ ]` / `- [x]` | v0.2 |
+
+### Visual output
+
+- Clickable PDF `/Link` annotations on every URL, inline links and autolinks alike.
+- Blue underlined link text.
+- Light-grey background tint behind fenced code blocks.
+- Thin grey vertical rules for blockquotes. Stacked side-by-side for nested quotes.
+- Tinted table headers with full grid borders and per-column alignment.
+- AFM-correct kerning emitted via TJ arrays (Helvetica and Times both fully kerned).
+- Strikethrough drawn as a thin horizontal bar at glyph mid-height.
+
+### Typography
+
+- Helvetica family (default) or Times family. Code uses Courier.
+- Standard PDF letter and A4 page sizes.
+- WinAnsi character encoding: em-dash, en-dash, curly quotes, ellipsis, most Western European glyphs.
+- Codepoints outside WinAnsi (CJK, Cyrillic, emoji, most non-Latin scripts) render as `?` in v0.1. v0.2 lifts this with font embedding.
+
+## Determinism
+
+`inkmd` produces **byte-identical** PDF output for the same markdown input on every platform, every Python version, every run. No real-time clocks, no random IDs, no platform-dependent iteration order.
+
+If you hash the markdown and the PDF, the relationship is stable forever. Useful for version-controlled documents, signed/hashed PDFs, reproducible CI builds, and audit trails.
+
+## What `inkmd` doesn't do yet
+
+| Feature | When | Why |
+|---------|------|-----|
+| Images | v0.2 | Needs decoding plus embedding logic; out of scope for v0.1 |
+| TTF / OTF font embedding | v0.2 | v0.1 uses PDF's 14 base fonts. Tiny output, no font files to ship, but limits codepoints to WinAnsi |
+| Task lists | v0.2 | GFM extension; needs list-marker prefix scan |
+| Headers, footers, page numbers | v0.2 | Needs a per-page chrome system |
+| Page-splitting for oversized tables | v0.2 | Tables currently place atomically and overflow if taller than a page |
+| Tables inside blockquotes | v0.2 | Table detection runs at document level only |
+| Tagged PDF / PDF/UA accessibility | v0.3+ | Under consideration |
+| PDF/A archival format | n/a | Not planned |
+| Math (LaTeX-style) | n/a | Out of scope. Use Pandoc + LaTeX. |
+| HTML passthrough | n/a | Out of scope by design. `inkmd` is markdown to PDF, not HTML to PDF. |
+| Themes / CSS | n/a | Out of scope. Markdown's value is its constraints. |
+
+## How it works
+
+Four layers, each strictly above the previous:
+
+1. **`parser`** is a single-pass container-aware block parser plus a CommonMark inline tokeniser. Produces a frozen-dataclass AST.
+2. **`render`** lowers AST blocks to `RenderedBlock` records with runs, spacing, indent, decorations. Carries font and link state through inline nesting.
+3. **`layout`** wraps runs into pages, positions each `PositionedRun` against the page coordinate system, emits background rectangles for code blocks, vertical rules for blockquotes, underline plus annotation pairs for links, and bars for strikethrough.
+4. **`pdf`** serialises pages into PDF bytes. Text via `Tj`/`TJ`-with-kerning, graphics via `rg`/`re`/`f`, link annotations via per-page `/Annots` arrays.
+
+No layer imports a higher one. The whole pipeline is around 3,500 lines of pure-Python logic plus 4,700 lines of generated AFM kerning tables. That's it. For a deeper walk-through (the emphasis algorithm, AFM kerning, determinism mechanics), see [`docs/internals.md`](docs/internals.md). The complexity profile is in [`LIZARD-AUDIT.md`](LIZARD-AUDIT.md).
+
+<details>
+<summary><strong>A note on font rendering in v0.1</strong></summary>
+
+`inkmd` v0.1 uses PDF's **14 base fonts** (Helvetica, Times, Courier, Symbol, ZapfDingbats and their variants). These are spec-mandated to be available in every conforming PDF reader, so we don't ship any font files. The output stays tiny and dependency-free.
+
+The trade-off is that the *actual rendering* depends on which Helvetica (or Times, etc.) the reader's system provides:
+
+- **macOS** ships Helvetica Neue (real Helvetica). Renders as designed.
+- **Windows** with Adobe Reader ships real Helvetica. Renders as designed.
+- **Linux** typically substitutes Nimbus Sans (URW++'s free Helvetica clone). Renders very similarly but with slightly different side bearings, so spacing between glyphs can look subtly different.
+- **Mobile** (iOS / Android) ships system Helvetica or Roboto variants. Mostly fine.
+
+The advance widths are correct everywhere (PDF readers honour the AFM-published metrics), so layout (page breaks, line wrapping, paragraph flow) is identical across systems. What varies is the precise glyph shape *within* each advance-width box, which can produce slightly different visual spacing.
+
+For most use cases this is fine. If you need pixel-identical rendering across every system (signed or archival documents, for example), wait for **v0.2 font embedding**, which will bundle font outlines inside each PDF.
+
+</details>
+
+## Roadmap
+
+- **v0.1**: Core CommonMark + GFM subset, library + CLI, MIT, deterministic. **Shipped.**
+- **v0.2**: Font embedding (full Unicode), images, task lists, headers/footers/page numbers, page-splitting for oversized tables, tables-in-blockquotes.
+- **v0.3**: Tagged PDF, accessibility, TOC generation, cross-references.
+- **post-v1.0**: Optimisations, additional page sizes, PDF/A consideration.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+## Acknowledgements
+
+The 14 standard PDF fonts and their AFM metric files are public-domain artefacts published by Adobe ([adobe-type-tools/Core14_AFMs](https://github.com/adobe-type-tools/Core14_AFMs)). PDF format reference: ISO 32000-1.
+
+## About
+
+Built by [Dylan Moir](https://www.linkedin.com/in/dylanmoir/) with Claude as a pair-programming collaborator. If `inkmd` saves you a fight with WeasyPrint or a 200 MB Chrome install in your CI, a star on the repo is plenty.

inkmd-0.1.0/README.md

@@ -0,0 +1,241 @@
+# inkmd
+
+**Markdown to PDF, pure Python, zero dependencies. MIT-licensed. Deterministic.**
+
+```sh
+pip install inkmd
+inkmd in.md -o out.pdf
+```
+
+That's the whole install. No system packages, no fonts to install, no Chrome binary, no `apt-get`. Works the same on macOS, Linux, Windows, Alpine, AWS Lambda, a locked-down CI runner, or a Steam Deck.
+
+<p align="center">
+  <img src="docs/images/hero-sample.png" alt="A quarterly report rendered by inkmd, showing headings, a styled paragraph with strikethrough, a blockquote, a right-aligned table with tinted header, a bulleted list, and a fenced Python code block with a grey background." width="640">
+  <br>
+  <em><a href="examples/hero-sample.md">examples/hero-sample.md</a> rendered through inkmd: headings, inline styles, strikethrough, blockquote, GFM table, list, fenced code, autolinked URL and email all in one page.</em>
+  <br>
+  <em>See also <a href="examples/inkmd-brief.md">examples/inkmd-brief.md</a>, a two-page project brief written in inkmd-renderable markdown.</em>
+</p>
+
+## What you get
+
+- **A single pure-Python wheel.** No native extensions, no system libraries. Installs in under a second.
+- **Faithful CommonMark plus the parts of GFM people actually use:** tables, autolinks, strikethrough, fenced code with language tags. The [supported features](#supported-markdown) section has the full matrix.
+- **PDFs that look right.** Real AFM-driven kerning emitted via TJ arrays, clickable links, tinted code-block backgrounds, blockquote rules that stack for nested quotes, table alignment, headings that breathe.
+- **Byte-identical output for the same input.** No clocks, no random IDs. Useful for version control, signed PDFs, audit trails, reproducible CI.
+- **Two layers of API:** a CLI and a `compile()` / `render_file()` library function. The whole public surface is two functions.
+
+## Why this exists
+
+Markdown to PDF is a solved problem in theory and a minefield in practice. Every other tool brings heavy system dependencies that don't survive the trip into an Alpine container, a Lambda function, or a Windows machine without admin rights.
+
+| Tool | What goes wrong |
+|------|-----------------|
+| **wkhtmltopdf** | Deprecated since 2023. Unpatched CVEs. |
+| **Chrome headless / Puppeteer** | 200MB+ install. 5 to 15s cold-start latency. |
+| **WeasyPrint** | Needs Pango, cairo, GObject (350 to 550MB of system packages). Breaks on Alpine and Windows. |
+| **Pandoc + LaTeX** | 3GB texlive install. |
+| **PyMuPDF-based tools** | Don't build on Alpine musl. |
+| **`borb`** | AGPL, so unusable in closed-source or commercial projects without a paid licence. |
+
+`inkmd` runs anywhere Python runs. It's the markdown-to-PDF compiler you'd write yourself with a free weekend if you didn't want to take a dependency on a browser.
+
+## Use cases
+
+- **CI documentation pipelines.** Compile READMEs, release notes, or changelogs to PDF as a build artefact, in a stripped-down container, without `apt-get`.
+- **Agent-generated documents.** LLM agents that need to deliver a PDF (CVs, reports, summaries) can call `inkmd.compile()` directly. No subprocess, no shell-out, no Chrome.
+- **Reproducible audit trails.** Hash the markdown, hash the PDF, and the same input gives the same output bytes. Useful for compliance, signed reports, version-controlled docs.
+- **Serverless rendering.** Lambda plus zero system dependencies equals a PDF endpoint that cold-starts in well under a second.
+- **Restricted environments.** Locked-down CI runners, embedded hardware, anywhere installing a 200MB browser isn't an option.
+
+## Status
+
+**v0.1, feature-complete, MIT-licensed.** 501 tests across 24 files. Stdlib-only, Python 3.9+. Byte-deterministic output. The [torture test](examples/torture-test.md) covers everything `inkmd` can render.
+
+## Install
+
+From PyPI:
+
+```sh
+pip install inkmd
+```
+
+Or grab the single-file zipapp (no `pip` install required). Each tagged release attaches an `inkmd.pyz` of around 300 KB that you can drop anywhere Python 3.9+ is available:
+
+```sh
+curl -L -o inkmd.pyz https://github.com/eagredev/inkmd/releases/latest/download/inkmd.pyz
+python inkmd.pyz in.md -o out.pdf
+```
+
+Or build it yourself from a checkout:
+
+```sh
+python scripts/build_zipapp.py    # produces dist/inkmd.pyz
+```
+
+## Usage
+
+### CLI
+
+```sh
+inkmd in.md -o out.pdf              # file in, file out
+inkmd in.md > out.pdf               # file in, stdout out
+inkmd < in.md > out.pdf             # stdin in, stdout out
+inkmd in.md -o out.pdf --page-size A4 --family times
+inkmd in.md -o out.pdf --no-autolinks
+inkmd --version
+```
+
+### Library
+
+```python
+import inkmd
+
+# Compile markdown text to PDF bytes
+pdf_bytes = inkmd.compile(md_text)
+
+# Or convert files directly
+inkmd.render_file("in.md", "out.pdf")
+
+# Options (same on both functions)
+pdf_bytes = inkmd.compile(
+    md_text,
+    page_size="A4",          # or "letter" (default)
+    family="times",          # or "helvetica" (default)
+    autolinks=False,         # opt out of GFM bare-URL/email detection
+)
+```
+
+The public API is intentionally narrow: two functions, no classes to instantiate, no state to manage. The CLI is a thin argparse wrapper around `compile()`.
+
+## Supported markdown
+
+### CommonMark
+
+| Feature | inkmd |
+|---------|:---:|
+| Paragraphs with line wrapping | Yes |
+| ATX headings (`#` to `######`) | Yes |
+| Setext headings (`===` / `---`) | Yes |
+| Ordered lists, arbitrary `start` | Yes |
+| Unordered lists (`-` / `*` / `+`) | Yes |
+| Nested lists, mixed marker types | Yes |
+| Tight vs. loose list detection | Yes |
+| Blockquotes | Yes |
+| Nested and multi-paragraph blockquotes | Yes |
+| Blockquotes wrapping any block type | Yes |
+| Fenced code blocks | Yes |
+| Code block language tag (info string) | Yes |
+| Indented code blocks | Yes |
+| Code spans (`` `code` ``) | Yes |
+| Emphasis (`*`, `_`) | Yes |
+| Strong emphasis (`**`, `__`) | Yes |
+| Triple `***` becomes nested italic-bold | Yes |
+| Rule of 3 plus intraword-underscore | Yes |
+| Backslash escapes | Yes |
+| Thematic breaks | Yes |
+| Inline links `[text](url)` | Yes |
+| Inline link titles | Yes |
+| Angle-bracket autolinks `<url>` | Yes |
+| Images `![](...)` | v0.2 |
+| Reference-style links | v0.2 |
+| HTML blocks / inline HTML | not planned |
+
+### GFM extensions
+
+| Feature | inkmd |
+|---------|:---:|
+| Pipe tables | Yes |
+| Table column alignments | Yes |
+| Bare URL autolinks (`https://...`, `www....`) | Yes |
+| Bare host autolinks (`host.tld/path`) | Yes |
+| Email autolinks | Yes |
+| Strikethrough `~~text~~` | Yes |
+| Task lists `- [ ]` / `- [x]` | v0.2 |
+
+### Visual output
+
+- Clickable PDF `/Link` annotations on every URL, inline links and autolinks alike.
+- Blue underlined link text.
+- Light-grey background tint behind fenced code blocks.
+- Thin grey vertical rules for blockquotes. Stacked side-by-side for nested quotes.
+- Tinted table headers with full grid borders and per-column alignment.
+- AFM-correct kerning emitted via TJ arrays (Helvetica and Times both fully kerned).
+- Strikethrough drawn as a thin horizontal bar at glyph mid-height.
+
+### Typography
+
+- Helvetica family (default) or Times family. Code uses Courier.
+- Standard PDF letter and A4 page sizes.
+- WinAnsi character encoding: em-dash, en-dash, curly quotes, ellipsis, most Western European glyphs.
+- Codepoints outside WinAnsi (CJK, Cyrillic, emoji, most non-Latin scripts) render as `?` in v0.1. v0.2 lifts this with font embedding.
+
+## Determinism
+
+`inkmd` produces **byte-identical** PDF output for the same markdown input on every platform, every Python version, every run. No real-time clocks, no random IDs, no platform-dependent iteration order.
+
+If you hash the markdown and the PDF, the relationship is stable forever. Useful for version-controlled documents, signed/hashed PDFs, reproducible CI builds, and audit trails.
+
+## What `inkmd` doesn't do yet
+
+| Feature | When | Why |
+|---------|------|-----|
+| Images | v0.2 | Needs decoding plus embedding logic; out of scope for v0.1 |
+| TTF / OTF font embedding | v0.2 | v0.1 uses PDF's 14 base fonts. Tiny output, no font files to ship, but limits codepoints to WinAnsi |
+| Task lists | v0.2 | GFM extension; needs list-marker prefix scan |
+| Headers, footers, page numbers | v0.2 | Needs a per-page chrome system |
+| Page-splitting for oversized tables | v0.2 | Tables currently place atomically and overflow if taller than a page |
+| Tables inside blockquotes | v0.2 | Table detection runs at document level only |
+| Tagged PDF / PDF/UA accessibility | v0.3+ | Under consideration |
+| PDF/A archival format | n/a | Not planned |
+| Math (LaTeX-style) | n/a | Out of scope. Use Pandoc + LaTeX. |
+| HTML passthrough | n/a | Out of scope by design. `inkmd` is markdown to PDF, not HTML to PDF. |
+| Themes / CSS | n/a | Out of scope. Markdown's value is its constraints. |
+
+## How it works
+
+Four layers, each strictly above the previous:
+
+1. **`parser`** is a single-pass container-aware block parser plus a CommonMark inline tokeniser. Produces a frozen-dataclass AST.
+2. **`render`** lowers AST blocks to `RenderedBlock` records with runs, spacing, indent, decorations. Carries font and link state through inline nesting.
+3. **`layout`** wraps runs into pages, positions each `PositionedRun` against the page coordinate system, emits background rectangles for code blocks, vertical rules for blockquotes, underline plus annotation pairs for links, and bars for strikethrough.
+4. **`pdf`** serialises pages into PDF bytes. Text via `Tj`/`TJ`-with-kerning, graphics via `rg`/`re`/`f`, link annotations via per-page `/Annots` arrays.
+
+No layer imports a higher one. The whole pipeline is around 3,500 lines of pure-Python logic plus 4,700 lines of generated AFM kerning tables. That's it. For a deeper walk-through (the emphasis algorithm, AFM kerning, determinism mechanics), see [`docs/internals.md`](docs/internals.md). The complexity profile is in [`LIZARD-AUDIT.md`](LIZARD-AUDIT.md).
+
+<details>
+<summary><strong>A note on font rendering in v0.1</strong></summary>
+
+`inkmd` v0.1 uses PDF's **14 base fonts** (Helvetica, Times, Courier, Symbol, ZapfDingbats and their variants). These are spec-mandated to be available in every conforming PDF reader, so we don't ship any font files. The output stays tiny and dependency-free.
+
+The trade-off is that the *actual rendering* depends on which Helvetica (or Times, etc.) the reader's system provides:
+
+- **macOS** ships Helvetica Neue (real Helvetica). Renders as designed.
+- **Windows** with Adobe Reader ships real Helvetica. Renders as designed.
+- **Linux** typically substitutes Nimbus Sans (URW++'s free Helvetica clone). Renders very similarly but with slightly different side bearings, so spacing between glyphs can look subtly different.
+- **Mobile** (iOS / Android) ships system Helvetica or Roboto variants. Mostly fine.
+
+The advance widths are correct everywhere (PDF readers honour the AFM-published metrics), so layout (page breaks, line wrapping, paragraph flow) is identical across systems. What varies is the precise glyph shape *within* each advance-width box, which can produce slightly different visual spacing.
+
+For most use cases this is fine. If you need pixel-identical rendering across every system (signed or archival documents, for example), wait for **v0.2 font embedding**, which will bundle font outlines inside each PDF.
+
+</details>
+
+## Roadmap
+
+- **v0.1**: Core CommonMark + GFM subset, library + CLI, MIT, deterministic. **Shipped.**
+- **v0.2**: Font embedding (full Unicode), images, task lists, headers/footers/page numbers, page-splitting for oversized tables, tables-in-blockquotes.
+- **v0.3**: Tagged PDF, accessibility, TOC generation, cross-references.
+- **post-v1.0**: Optimisations, additional page sizes, PDF/A consideration.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+## Acknowledgements
+
+The 14 standard PDF fonts and their AFM metric files are public-domain artefacts published by Adobe ([adobe-type-tools/Core14_AFMs](https://github.com/adobe-type-tools/Core14_AFMs)). PDF format reference: ISO 32000-1.
+
+## About
+
+Built by [Dylan Moir](https://www.linkedin.com/in/dylanmoir/) with Claude as a pair-programming collaborator. If `inkmd` saves you a fight with WeasyPrint or a 200 MB Chrome install in your CI, a star on the repo is plenty.

inkmd-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "inkmd"
+version = "0.1.0"
+description = "Pure-Python markdown to PDF compiler. Zero system dependencies. Deterministic."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Dylan Moir" },
+]
+keywords = ["markdown", "pdf", "compiler", "deterministic", "zero-dependencies"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Printing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+inkmd = "inkmd.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/eagredev/inkmd"
+Repository = "https://github.com/eagredev/inkmd"
+Issues = "https://github.com/eagredev/inkmd/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"

inkmd-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

inkmd-0.1.0/src/inkmd/__init__.py

@@ -0,0 +1,59 @@
+"""inkmd — pure-Python markdown to PDF compiler.
+
+Public API:
+
+    inkmd.compile(md_text: str, page_size: str = "letter", family: str = "helvetica") -> bytes
+        Parse markdown into PDF bytes.
+
+    inkmd.render_file(in_path, out_path, page_size: str = "letter", family: str = "helvetica") -> None
+        Read a markdown file, write a PDF file.
+
+Font family choices: 'helvetica' (default, sans-serif) or 'times' (serif).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from inkmd.parser import parse
+from inkmd.pdf import styled_pdf
+from inkmd.render import FAMILIES, render_document
+
+
+__version__ = "0.1.0"
+
+
+def compile(
+    md_text: str,
+    page_size: str = "letter",
+    family: str = "helvetica",
+    *,
+    autolinks: bool = True,
+) -> bytes:
+    """Compile markdown text into PDF bytes.
+
+    ``autolinks`` controls GFM-style detection of bare URLs and email
+    addresses (default True). Set False for strict CommonMark — bare
+    URLs render as plain text and only `<url>` / `[text](url)` produce
+    links.
+    """
+    if family not in FAMILIES:
+        raise ValueError(f"unknown family {family!r}; available: {tuple(FAMILIES)}")
+    doc = parse(md_text, autolinks=autolinks)
+    paragraphs = render_document(doc, family=FAMILIES[family])
+    return styled_pdf(paragraphs, page_size=page_size)
+
+
+def render_file(
+    in_path: str | Path,
+    out_path: str | Path,
+    page_size: str = "letter",
+    family: str = "helvetica",
+    *,
+    autolinks: bool = True,
+) -> None:
+    """Read markdown from ``in_path``; write PDF to ``out_path``."""
+    md = Path(in_path).read_text(encoding="utf-8")
+    Path(out_path).write_bytes(
+        compile(md, page_size=page_size, family=family, autolinks=autolinks)
+    )

inkmd-0.1.0/src/inkmd/__main__.py

@@ -0,0 +1,4 @@
+from inkmd.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())