@ryhrm-gz/xincodo-lib
Version:
Utilities for working with Xincodo body documents.
176 lines (127 loc) • 4.3 kB
Markdown
name: extracting-render-metadata
description: >
Load when extracting article or preview metadata from Xincodo Body data
with toPlainText, richTextToPlainText, extractHeadings,
extractHeadingAnchors, slugifyHeading, createExcerpt,
estimateReadingTime, collectImageSources, or collectLinks.
type: core
library: "@ryhrm-gz/xincodo-lib"
library_version: "0.1.0"
requires:
- building-and-parsing-body
sources:
- "ryhrm-gz/xincodo-lib:README.md"
- "ryhrm-gz/xincodo-lib:src/rendering.ts"
- "ryhrm-gz/xincodo-lib:src/utils.ts"
- "ryhrm-gz/xincodo-lib:src/traversal.ts"
- "ryhrm-gz/xincodo-lib:tests/rendering.test.ts"
# Extracting Render Metadata
This skill builds on `building-and-parsing-body`. Use these helpers to prepare
metadata for preview and article pages; do not use them as UI renderers.
## Setup
```ts
import {
collectImageSources,
collectLinks,
createExcerpt,
estimateReadingTime,
extractHeadingAnchors,
toPlainText,
} from "@ryhrm-gz/xincodo-lib";
const metadata = {
plainText: toPlainText(body),
headings: extractHeadingAnchors(body),
excerpt: createExcerpt(body, { maxLength: 120, preserveWords: true }),
readingTime: estimateReadingTime(body),
images: collectImageSources(body),
links: collectLinks(body),
};
```
## Core Patterns
### Build table-of-contents data
```ts
import { extractHeadingAnchors } from "@ryhrm-gz/xincodo-lib";
const tableOfContents = extractHeadingAnchors(body).map((heading) => ({
id: heading.anchorId,
href: heading.href,
level: heading.level,
text: heading.text,
}));
```
`extractHeadingAnchors` preserves existing heading ids by default, creates
unique slugs, and URI-encodes href values.
### Create listing metadata
```ts
import { createExcerpt, estimateReadingTime, toPlainText } from "@ryhrm-gz/xincodo-lib";
const listing = {
text: toPlainText(body),
excerpt: createExcerpt(body, { maxLength: 160, preserveWords: true }),
readingTime: estimateReadingTime(body),
};
```
`estimateReadingTime` accounts for Latin words and CJK characters.
### Collect linked resources
```ts
import { collectImageSources, collectLinks } from "@ryhrm-gz/xincodo-lib";
const resources = {
imageUrls: collectImageSources(body).map((item) => item.source.url),
externalHrefs: collectLinks(body)
.filter((link) => link.kind === "text_link")
.map((link) => link.href),
pageReferences: collectLinks(body).filter((link) => link.kind === "page_link"),
};
```
Image sources include image blocks, gallery images, and callout image icons.
## Common Mistakes
### HIGH Building heading hrefs by hand
Wrong:
```ts
import { extractHeadings } from "@ryhrm-gz/xincodo-lib";
const hrefs = extractHeadings(body).map(
(heading) => `#${heading.text.toLowerCase().replaceAll(" ", "-")}`,
);
```
Correct:
```ts
import { extractHeadingAnchors } from "@ryhrm-gz/xincodo-lib";
const hrefs = extractHeadingAnchors(body).map((heading) => heading.href);
```
Manual slugging can duplicate anchors, ignore existing ids, or fail to encode
CJK headings correctly.
Source: `src/rendering.ts`; `tests/rendering.test.ts`
### HIGH Collecting only image blocks
Wrong:
```ts
const images = body.content.filter((block) => block.type === "image").map((block) => block.source);
```
Correct:
```ts
import { collectImageSources } from "@ryhrm-gz/xincodo-lib";
const images = collectImageSources(body).map((item) => item.source);
```
Renderable image sources can appear in image blocks, gallery images, and
callout image icons.
Source: `src/rendering.ts`; `tests/rendering.test.ts`
### MEDIUM Assuming excerpts preserve words
Wrong:
```ts
import { createExcerpt } from "@ryhrm-gz/xincodo-lib";
const excerpt = createExcerpt(body, { maxLength: 120 });
```
Correct:
```ts
import { createExcerpt } from "@ryhrm-gz/xincodo-lib";
const excerpt = createExcerpt(body, {
maxLength: 120,
preserveWords: true,
});
```
`createExcerpt` truncates by character length unless `preserveWords` is
explicitly enabled.
Source: `README.md`; `src/rendering.ts`; `tests/rendering.test.ts`
## References
- [Metadata helper return shapes](references/metadata-helper-return-shapes.md)
See also: `article-render-preparation/SKILL.md` — article page preparation
composes these extraction APIs into an application workflow.