Metadata-Version: 2.5
Name: hamen-markup
Version: 1.0.0
Summary: A programmable document language for complex web and PDF composition
Project-URL: Homepage, https://hamen.dev/products/markup
Project-URL: Documentation, https://hamen.dev/markup/docs/1.0.0/
Author: Daniel Hamen
License: MIT License
        
        Copyright (c) 2026 Daniel Hamen and Hamen Systems & Research
        
        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.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: pint<1,>=0.24
Requires-Dist: pygments<3,>=2.18
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: markdown-it-py<5,>=3; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pypdf; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: types-pygments; extra == 'dev'
Provides-Extra: pdf
Requires-Dist: playwright<2,>=1.50; extra == 'pdf'
Provides-Extra: science
Requires-Dist: rdkit>=2024.9; extra == 'science'
Description-Content-Type: text/markdown

# Hamen Markup

Write expressive notes at typing speed, then export them to the web or PDF. Hamen Markup 1.0.0 is a local Python compiler with a browser-based notes editor, reusable document components, and bundled rendering assets. Free under the MIT license.

[Product and downloads](https://hamen.dev/products/markup) · [Technical documentation](https://hamen.dev/markup/docs/1.0.0/) · [Installation](docs/INSTALL.md) · [Release policy](docs/RELEASE.md)

## Notes

Write notes with concise headings, expressive marks, keyboard math, diagrams, anchored annotations, worked calculations, and recall prompts. Use `:::box`, `:::aside`, and `:::fold` for nested blocks, and `- [ ]` for checklists. The local editor includes immediate preview, shorthand, section rearrangement, undo, and conflict-aware saving.

```sh
.venv/bin/hmk edit examples/learning-notes.hmn --root .
```

Open the printed address. For a new note, use `hmk edit my-notes.hmn`. Notes mode requires no document wrapper. See [the notes guide](docs/NOTES.md) for the syntax, editor commands, and limits. Existing `.hmk` documents retain their behavior; `.hmn` enables notes syntax, or add `@Notes()` to a `.hmk` file.

## Start here

Python 3.12 or newer is required. Follow [installation](docs/INSTALL.md) for a release wheel, or install from the source archive using the instructions below. After installation, from the project directory:

```sh
source .venv/bin/activate
hmk serve examples/editorial.hmk --root .
```

Open the printed local preview address. Changes to the document and its imported assets rebuild the preview automatically.

For a fresh checkout:

```sh
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev,pdf,science]'
python -m playwright install chromium
```

Browser libraries and default fonts are bundled in the Python package. Node.js is only needed when updating those bundled dependencies.

## Build and check

```sh
hmk check examples/editorial.hmk --root .
hmk build examples/editorial.hmk --root . -o output/editorial.html
hmk build examples/editorial.hmk --root . -o output/editorial.pdf
hmk inspect examples/editorial.hmk
hmk components Grid
hmk pack examples/editorial.hmk --root . -o output/editorial.hmkp
hmk unpack output/editorial.hmkp output/unpacked-editorial
```

An HTML export consists of the HTML file and its adjacent `.assets` directory. Publish both together. Embed it with an iframe to preserve its document styles and interactive runtime:

```html
<iframe src="/documents/editorial.html" title="Research notes"
        style="width:100%;height:900px;border:0"></iframe>
```

## Examples

- `examples/learning-notes.hmn` — all notes features in one editable document.
- `examples/getting-started.hmk` — the original outline made executable, including columns, chemistry, equations, references, and page numbers.
- `examples/editorial.hmk` — a two-page editorial layout with grids, custom components, a chart, a table, and a diagram.
- `examples/layout-lab.hmk` — canvas layers, exact coordinates, linked text frames, and constraints.
- `examples/responsive.hmk` — responsive layout, disclosures, and local form controls.
- `examples/science.hmk` — SMILES molecular structures, math, chemistry, unit conversion, and citations.
- `examples/interactive-3d.hmk` — a local GLB viewer with a static PDF illustration.
- `examples/page-masters.hmk` — repeated page decoration and footnotes.

Read [the implemented syntax](docs/SYNTAX.md), [capabilities and boundaries](docs/IMPLEMENTATION.md), [the component catalogue](docs/COMPONENTS.md), and [validation results](docs/VALIDATION.md).

## Python API

```python
from hamen_markup import compile_file, compile_source
from hamen_markup.export import export_pdf

web = compile_source("@DocumentType(Pageless)\n@P: Hello, world!")
web.write("output/hello.html")

document = compile_file("examples/editorial.hmk", root=".", target="pdf")
export_pdf(document, "output/editorial.pdf")
```

In an application with a running asyncio event loop, run synchronous PDF export in a worker thread, for example with `await asyncio.to_thread(export_pdf, document, path)`.

## Development checks

```sh
pytest -q
ruff check src/hamen_markup tests tools/vendor.py tools/make_demo_assets.py
mypy src/hamen_markup
python -m build
```

Use `pytest -m 'not browser'` for parser, component, packaging, and validation tests without launching Chromium. Browser tests check actual geometry and interaction; they require the PDF extra and Chromium.

To rebuild third-party assets from their pinned lockfile:

```sh
npm ci --prefix tools/vendor --ignore-scripts
python tools/vendor.py
```

## Project goals

- Keep ordinary prose concise and readable in source form.
- Support paged documents and responsive pageless documents.
- Render web and PDF output through a shared visual model.
- Combine flowing text, grids, constraints, layers, and exact-positioned canvas layouts.
- Provide reusable, typed components instead of unrestricted textual macros.
- Include first-class math, chemistry, diagrams, citations, and media.
- Require deterministic static fallbacks for interactive content in PDF output.
- Produce useful diagnostics with source locations and actionable messages.
- Remain extensible without allowing documents unrestricted access to the host system.

## Proposed source extension

`.hmk` contains document source; `.hmkp` is a verified portable source bundle. The compiler accepts the original `@MarkupVersion(1.0.0)` sketch and `0.1.0` / `0.2.1` as experimental syntax versions. This does not mean the compiler is a stable 1.0 release.

## Repository map

- `docs/COMPONENTS.md` — full component design catalogue and implemented-contract links.
- `docs/SYNTAX.md` — executable syntax and examples.
- `docs/IMPLEMENTATION.md` — current feature contracts and limitations.
- `docs/LANGUAGE_DESIGN.md` — language principles, syntax, and layout model.
- `docs/ARCHITECTURE.md` — compiler and rendering architecture.
- `docs/ROADMAP.md` — release milestones and remaining development phases.
- `examples/` — runnable demonstration documents.
- `src/hamen_markup/` — Python compiler, browser runtime, and bundled libraries.
- `tests/` — language, component, source-bundle, browser, and PDF tests.
- `assets/` — local fonts, images, and models used by examples and tests.

## Status

Experimental implementation. All component names from the initial catalogue are registered, with concrete supported contracts documented in `docs/IMPLEMENTATION.md`. Advanced design aspirations in the catalogue are not all compatibility promises. In particular, nonlinear constraint solving, a public package registry, full CSL bibliography styling, arbitrary embedded applications, and press-certified PDF/X or PDF/UA conformance are outside this release.

## License

Project code and original demo assets: MIT. See `LICENSE`. Bundled dependencies and fonts retain their own licenses; see `THIRD_PARTY_NOTICES.md`.
