Metadata-Version: 2.5
Name: zensical-carve
Version: 0.1.2
Summary: Carve markup support for Zensical, the successor to MkDocs
Project-URL: Homepage, https://github.com/markup-carve/zensical-carve
Project-URL: Source, https://github.com/markup-carve/zensical-carve
Project-URL: Issues, https://github.com/markup-carve/zensical-carve/issues
Project-URL: Changelog, https://github.com/markup-carve/zensical-carve/blob/main/CHANGELOG.md
Project-URL: Carve, https://markup-carve.github.io/carve/
Author: markup-carve
License: MIT License
        
        Copyright (c) 2026 Mark Scherer
        
        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
Keywords: carve,documentation,markup,mkdocs,static-site-generator,zensical
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: carve-lang<0.2.0,>=0.1.1
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: zensical>=0.0.56; extra == 'dev'
Provides-Extra: zensical
Requires-Dist: zensical>=0.0.56; extra == 'zensical'
Description-Content-Type: text/markdown

# zensical-carve

Use [Carve][carve] in a [Zensical][zensical] site, either as a block inside a
Markdown page or as a complete `.crv` page.

```bash
pip install zensical-carve
```

## Carve blocks in Markdown

Register a `pymdownx.superfences` custom fence in `zensical.toml`:

```toml
pymdownx.superfences.custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
  { name = "carve", class = "carve", format = "zensical_carve.fence" },
]
```

The formatter uses a dot between the module and function. Zensical does not
accept the `module:function` spelling here.

````markdown
```carve
## Rendered by Carve

A *bold* and /italic/ line.
```
````

## Complete Carve pages

Zensical does not discover `.crv` files as pages, so render them before the
site build:

```bash
zensical-carve prepare
zensical build
```

After configuration changes, use the combined command so it passes `--clean`
and avoids stale generated pages:

```bash
zensical-carve build
```

The converter writes a Markdown page beside each source. It returns headings
and code blocks to Zensical as Markdown so the theme can build navigation,
permalinks, syntax highlighting, and code controls. Other constructs remain
Carve HTML to avoid a lossy whole-document Markdown conversion.

Frontmatter is copied to the generated page for Zensical to read.

## Configuration

Settings may live in `[tool.zensical-carve]` inside `zensical.toml` or
`pyproject.toml`:

```toml
[tool.zensical-carve]
extensions = ["details", "tabs", "math-block"]
emoji = "twemoji"
docs-dir = "docs"
```

Command-line flags override the file. Configuration also controls symbol maps,
raw HTML, diagram prerendering, and the Kroki endpoint. The default public
Kroki service receives diagram source; use a private endpoint when needed.

## Includes and build output

Includes are off by default. Enable them with `includes = true` or
`--includes`; this requires carve-lang 0.1.4 or newer. Carve fences inside
Markdown pages never expand includes. Generated pages record their source and
a generated marker.

## Feature support

Most Carve HTML works directly. Theme-sensitive constructs, diagrams, emoji,
heading links, code blocks, and diff blocks receive specific adapters. See the
[feature matrix](https://github.com/markup-carve/zensical-carve/blob/main/docs/reference.md#which-carve-features-work) and
[collision measurements](https://github.com/markup-carve/zensical-carve/blob/main/docs/reference.md#collisions-with-zensical-measured)
before enabling a large extension set.

## Reference

The [complete reference](https://github.com/markup-carve/zensical-carve/blob/main/docs/reference.md) documents configuration, commands,
includes, theme adaptation, diagrams, reference documents, and known Zensical
limits.

## Development

Contributor setup, tests, and maintenance commands are in the
[development guide](https://github.com/markup-carve/zensical-carve/blob/main/docs/development.md).
Release steps are in the
[release guide](https://github.com/markup-carve/zensical-carve/blob/main/docs/releasing.md).

[carve]: https://markup-carve.github.io/carve/
[zensical]: https://zensical.org/
