Metadata-Version: 2.4
Name: comverter
Version: 0.1.0
Summary: ComVerter - The Common Converter
Keywords: converter,commonmark,markdown
Author-Email: CodeWriter21 <CodeWriter21@gmail.com>
License-Expression: MIT
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Project-URL: Homepage, https://github.com/MPCodeWriter21/comverter
Project-URL: Repository, https://github.com/MPCodeWriter21/comverter.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown

ComVerter - The Common Converter
================================

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/MPCodeWriter21/comverter/actions/workflows/ci.yml/badge.svg)](https://github.com/MPCodeWriter21/comverter/actions/workflows/ci.yml)

ComVerter is a simple C Python extension that I plan to use for converting some simple
formats to others. Like Markdown to HTML, HTML to PDF, and many others.

Features
--------

- [x] Markdown to HTML
- [ ] HTML to PDF

Want another format? [Open an issue](https://github.com/MPCodeWriter21/comverter/issues)
or [submit a pull request](https://github.com/MPCodeWriter21/comverter/pulls).

Build & Install (Release)
-------------------------

This project uses [uv](https://docs.astral.sh/uv/) as the release build tool.

```bash
# Build the wheel for the current Python version
uv build --wheel

# Install the wheel
uv pip install dist/comverter-*.whl
```

Usage
-----

```python
>>> from comverter import markdown_to_html, markdown_file_to_html, ALL_MARKDOWN_EXTENSIONS

>>> markdown_to_html("Hello, **world**!")
'<p>Hello, <strong>world</strong>!</p>\n'

# Convert a Markdown file to HTML
>>> markdown_file_to_html("input.md", "output.html")

# Enable all extensions at once
>>> markdown_to_html("Hello **world**", extensions=ALL_MARKDOWN_EXTENSIONS)
'<p>Hello <strong>world</strong></p>\n'

# Enable extensions individually
>>> markdown_to_html("http://example.com", extensions=["autolink"])
'<p><a href=\"http://example.com\">http://example.com</a></p>\n'

>>> markdown_to_html("<script>", extensions=["tagfilter"])
'&lt;script>\n'
```

### Supported Markdown features

- **ATX headings** — `# H1` through `###### H6`
- **Paragraphs** — consecutive lines of text
- **Emphasis** — `*italic*` and `_italic_`
- **Strong emphasis** — `**bold**` and `__bold__`
- **Code spans** — `` `code` ``
- **Links** — `[text](url)` with optional `"title"`
- **Images** — `![alt](src)` with optional `"title"`
- **Fenced code blocks** — `` ``` `` and `` ~~~ ``
- **Blockquotes** — `> quote`
- **Unordered lists** — `- item`, `* item`, `+ item`
- **Ordered lists** — `1. item`
- **Thematic breaks** — `---`, `***`, `___`
- **Hard line breaks** — two trailing spaces
- **Backslash escapes** — `\*`, `\[`, etc.
- **Automatic HTML escaping** — `<`, `>`, `&`, `"`
- **Setext headings** — `Heading\n===` (level 1) and `Heading\n---` (level 2)
- **GFM pipe tables** — `\| a \| b \|\n\|---\|---\|\n\| 1 \| 2 \|` with optional alignment

### Extensions

Pass the `extensions` parameter with a list of extension names, or use
`ALL_MARKDOWN_EXTENSIONS` to enable all at once.

| Extension      | Description                                                |
|----------------|------------------------------------------------------------|
| `"autolink"`   | Auto-link URLs and email addresses                         |
| `"tagfilter"`  | Filter out certain HTML tags for security                  |

See [docs/md_extensions.md](./docs/md_extensions.md) for detailed documentation of each extension.

Development
----------

### Makefile targets

Run `make help` to see all available targets:

| Target            | Description                              |
|-------------------|------------------------------------------|
| `make setup`      | Create venv and configure meson          |
| `make reconfigure`| Reconfigure meson                        |
| `make build`      | Build the C extension and wheel          |
| `make install`    | Install the package in editable mode     |
| `make test`       | Run tests (stop after 3 failures)        |
| `make format`     | Run all source formatters                |
| `make test-all`   | Run all tests                            |
| `make clean`      | Remove all build artifacts               |

### LSP

Once meson is configured (`make setup`), `compile_commands.json` is
generated automatically, giving you completions, diagnostics, and
go-to-definition for the Python C API.

Task Management
---------------

This project uses [Tigo](https://github.com/MPCodeWriter21/Tigo) for task
management. Tasks are stored as `TASK.md` files under `.tigo/YYYYMMDD-HHmmss/`.

Disclaimer
----------

This repository is being developed using AI assistance.

References
----------

- [Python C API](https://docs.python.org/3/c-api/index.html)
- [GitHub Flavored Markdown](https://github.github.com/gfm/)
- [CommonMark](https://spec.commonmark.org/0.31.2/)
- [Markdown on WikiPedia](https://en.wikipedia.org/wiki/Markdown)
- [HTML Spec](https://html.spec.whatwg.org/)
- [RFC 2854](https://datatracker.ietf.org/doc/html/rfc2854)
- [RFC 7763](https://datatracker.ietf.org/doc/html/rfc7763)
- [RFC 7764](https://datatracker.ietf.org/doc/html/rfc7764)
- [RFC 8118](https://datatracker.ietf.org/doc/html/rfc8118)
