82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
|
# Source Attachment Metadata
|
||
|
|
|
||
|
|
`markitect-filter` exposes read-side attachment metadata through
|
||
|
|
`NormalizedMarkdownDocument.attachments`. These entries are
|
||
|
|
`markitect_tool.source.SourceAsset` objects, so `markitect-tool` can consume
|
||
|
|
them when building passive render asset manifests.
|
||
|
|
|
||
|
|
The metadata schema marker is:
|
||
|
|
|
||
|
|
```text
|
||
|
|
markitect-filter.source-attachment.v1
|
||
|
|
```
|
||
|
|
|
||
|
|
## Common Fields
|
||
|
|
|
||
|
|
Attachment entries should preserve:
|
||
|
|
|
||
|
|
- `uri`: stable source package or document member URI
|
||
|
|
- `path`: package member path or signal path
|
||
|
|
- `name`: member filename or signal label
|
||
|
|
- `media_type` and `extension` when known
|
||
|
|
- `size` and `digest` when bytes are available
|
||
|
|
- `metadata.source_adapter`: adapter id such as `source.epub3` or `source.pdf`
|
||
|
|
- `metadata.source_role`: logical read-side role
|
||
|
|
- `metadata.package_path`, `metadata.page`, `metadata.pdf_object`, or related
|
||
|
|
provenance coordinates when known
|
||
|
|
- `metadata.render_manifest_compatible: true` when the entry can feed
|
||
|
|
`RenderAsset.from_source_asset`
|
||
|
|
|
||
|
|
These entries describe source-side resources only. They do not imply output
|
||
|
|
paths, copy execution, final artifact locations, or publication state.
|
||
|
|
|
||
|
|
## EPUB3
|
||
|
|
|
||
|
|
The EPUB3 adapter records manifest resources for images, stylesheets, fonts,
|
||
|
|
audio, and video when the package entry exists and can be read cheaply from the
|
||
|
|
ZIP archive. It stores byte size and sha256 digest for each collected resource.
|
||
|
|
|
||
|
|
Unsupported non-XHTML package resources produce
|
||
|
|
`source.epub3.skipped_resource` warnings. Declared but missing resources produce
|
||
|
|
`source.epub3.missing_resource` warnings.
|
||
|
|
|
||
|
|
## PDF
|
||
|
|
|
||
|
|
The PDF adapter records embedded file streams when a stdlib scan can identify
|
||
|
|
`Filespec` and `EmbeddedFile` objects. It stores member bytes, media type by
|
||
|
|
filename, size, digest, object id, and source role `embedded-file`.
|
||
|
|
|
||
|
|
For image resources, the stdlib slice records signal-only entries with source
|
||
|
|
role `image-signal`. These entries preserve page/object provenance and a stable
|
||
|
|
digest of the detected page/resource signal, but they do not extract image
|
||
|
|
bytes. Image signals emit `source.pdf.image_resource_signal` warnings so callers
|
||
|
|
know the adapter detected media that it did not extract.
|
||
|
|
|
||
|
|
## Render Manifest Handoff
|
||
|
|
|
||
|
|
`markitect-tool` can convert attachment entries to passive render assets:
|
||
|
|
|
||
|
|
```python
|
||
|
|
from markitect_tool.render import RenderAsset
|
||
|
|
|
||
|
|
render_assets = [
|
||
|
|
RenderAsset.from_source_asset(asset, role=asset.metadata["source_role"])
|
||
|
|
for asset in document.attachments
|
||
|
|
]
|
||
|
|
```
|
||
|
|
|
||
|
|
The resulting render assets remain passive descriptors. Asset copying,
|
||
|
|
renderer output references, link rewriting, and final artifact validation stay
|
||
|
|
outside `markitect-filter`.
|
||
|
|
|
||
|
|
Example normalized attachment envelopes live in:
|
||
|
|
|
||
|
|
- `examples/source-attachments/epub3-attachments.normalized.yaml`
|
||
|
|
- `examples/source-attachments/pdf-attachments.normalized.yaml`
|
||
|
|
|
||
|
|
Cross-repo validation can be run from this checkout with:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
PYTHONPATH=src:/home/worsch/markitect-tool/src python3 -m pytest
|
||
|
|
```
|