Skip to content
Teasim
@yiplex/astro documentation
Astro

@yiplex/astro

The content layer — navigation, validation, markdown twins, and machine-readable routes.

@yiplex/astro is the half of a documentation site that has nothing to do with how it looks. It validates content, computes navigation, and publishes human and machine-readable routes without rendering a component.

This guide targets Astro integration 0.1.4. The package requires Node.js 24.2.0 or later and Astro >=7.2.10; it has no TeaCSS peer.

Install

sh
bun add @yiplex/[email protected] astro@^7.4.2

Configure the @yiplex registry and package-read credential as shown in Astra installation. Register yiplex() from @yiplex/astro in astro.config.mjs, then define collections with contentCollection() so their mounts can be shared by HTML pages, markdown twins, and llms.txt.

ts
import { defineConfig } from "astro/config";
import { yiplex } from "@yiplex/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [yiplex()],
});

site belongs to Astro configuration; integration options belong to yiplex(). The integration manages MDX and the supported code-notation transformers, while the application supplies the page layout and routes. astro is the only required peer. satteri is an optional type peer already installed by Astro. @yiplex/atlas, pagefind, and @astrojs/rss are optional peers needed only for micro-application hosting, search, and RSS respectively; ordinary content sites do not need to add them. The CLI’s init command preserves existing declared dependency versions, so it is not an upgrade command.

Core responsibilities

  • Validate content while naming the entry that needs attention
  • Build sidebars, breadcrumbs, table-of-contents data, and previous/next links
  • Serve a .md twin for every published page
  • Generate llms.txt and llms-full.txt from the same content

Why it is separate

A content helper that also renders markup decides how your site is built. That is a borrowed decision, so computing stays separate from rendering: @yiplex/astro renders nothing, while @yiplex/astra and @yiplex/aster know nothing about content. Either half works on its own.

Validation that names the page

Collection schemas validate frontmatter. After loading a collection, use composeEntries from @yiplex/astro/content; it preserves the collection entries for rendering and maps their complete metadata for navigation:

ts
import { getCollection } from "astro:content";
import { composeEntries } from "@yiplex/astro/content";
import { getNavigation } from "@yiplex/astro";

const docs = composeEntries(await getCollection("docs"), { name: "docs" });
const navigation = getNavigation(docs.entries, { base: "/docs" });
// docs.collection retains the loaded collection; docs.routable feeds HTML routes.

Composition reports content problems by slug in development by default; validate: true enables that reporting explicitly in another environment. Use validateContent to inspect the reported problems or assertContent to fail an explicit validation gate. Retain collection / routable for Astro render() and route generation, and entries for navigation. Hand-mapping only titles and slugs discards metadata such as prev, next, and externalLink before validation can see it.

Continue reading

See Project structure for a complete site scaffold and createNavigation for the navigation API.