Aster — Projects and writing, built with Astro

A Tour of Prosefly's Astro Components

Thu, 01 Oct 2026 00:00:00 GMT

@prosefly/astro-components is the shared MDX layer used by Lotus and Dahlia. It exists because technical articles regularly need more structure than Markdown provides, but that structure should not tie the writing to one documentation theme.

This page renders every public component from version 0.7.1 inside Aster. It is both a tour and a portability test: Aster supplies its own layouts, typography, colors, and spacing while the package supplies content structure and focused interactions.

One integration

Aster registers proseflyComponents() once. The integration supplies shared Markdown transforms, gallery assets, and Iconify preloading.

The examples stay inside one article on purpose. A component can look convincing in an isolated catalog and still feel too heavy when surrounded by real headings, paragraphs, and code. Seeing the whole set in sequence makes the intended hierarchy clearer.

Badges, icons, and callouts

Badges carry short metadata without interrupting a paragraph:

Astro 7 MDX Stable Private

Icons can be decorative or carry an accessible title. This icon is decorative; this one announces its meaning.

Use the lightest component that explains the idea

A badge labels, an icon cues, and a callout interrupts. Choosing between them is part of writing the page.

Cards and steps

Lotus

A complete documentation shell with navigation, search, and configurable design tokens.

Dahlia

A minimal, content-first theme built on the same component layer.

Install the package.

pnpm add @prosefly/astro-components

npm install @prosefly/astro-components

yarn add @prosefly/astro-components

bun add @prosefly/astro-components

Register the integration.

Add proseflyComponents() to astro.config.mjs.
Import components in MDX.

Keep ordinary prose in Markdown and reach for components only when structure helps.

Tabs and accordions

Tabs work well when several commands complete the same task.

pnpm add @prosefly/astro-components

npm install @prosefly/astro-components

Accordions keep optional answers available without lengthening the main path.

Can the components work without Lotus or Dahlia?

Yes. Register the shared integration and map the semantic Prosefly CSS properties to the surrounding site’s design tokens.

Do Prosefly themes need extra setup?

No. Lotus and Dahlia already register the integration and expose the shared components to their MDX content.

File trees

FileTree turns a single Markdown list into an expandable project map.

Directory src
- Directory content
  - Directory blog
    astro-components-tour.mdx
  - projects
- content.config.ts
- pages
astro.config.mjs
package.json

Image galleries

ImageGallery keeps related screenshots together and owns its responsive browser behavior.

Rich links and audio

Supplying complete metadata lets Embed render a link card without fetching the destination during the build.

Prosefly

Astro Theme Lotus

An installable documentation theme for Astro v7, Tailwind CSS v4, and MDX.

AudioPlayer enhances the native audio element with metadata, seeking, playback speed, mute, and Media Session support where the browser provides it.

STS-133 Mission Status Briefing

NASA mission audioNASA

Your browser does not support the audio element.

00:0011:06

Choosing the smallest useful component

The package is not meant to replace ordinary Markdown. Most sentences, lists, links, images, and code blocks should remain native content. A component earns its place when it adds a relationship or behavior that Markdown cannot express clearly.

Label

Use a badge for compact status or category metadata that belongs beside the prose.

Interrupt

Use a callout when a note, warning, or recommendation should change how the reader interprets the surrounding section.

Organize

Use cards, steps, tabs, accordions, or a file tree when the relationship between several pieces is the point.

Enhance media

Use a gallery, embed, or audio player when native media needs grouping, metadata, or focused controls.

That restraint keeps an MDX page readable in source form and makes the component API easier to maintain. The important boundary is unchanged across every example: components supply structure and behavior, while the host site supplies the visual system.

One Component Layer, Two Astro Themes

Tue, 22 Sep 2026 00:00:00 GMT

Lotus and Dahlia solve the same broad problem: turn an Astro content collection into a complete documentation site. Authors should not have to relearn how to write a callout or set of tabs when they move between them. Readers, however, should be able to feel that the themes make different choices.

That tension led to a simple boundary: share the author-facing component layer, but let each theme own its shell and visual system.

Extract the stable vocabulary

The shared @prosefly/astro-components package owns structures whose meaning does not change with the page layout.

Shared contract

MDX component APIs, accessible interaction behavior, Markdown transforms, icon loading, and semantic style hooks.

Theme-owned expression

Typography, spacing, color, header, sidebar, table of contents, search UI, and responsive page composition.

A tab still represents parallel choices in either theme. A callout still interrupts the prose with important context. Those semantics belong with the content. How much space they occupy and how they fit the surrounding article belong with the theme.

Directory @prosefly/astro-components
- MDXcomponents
- clientbehavior
- Markdowntransforms
- semanticCSS properties
Directory @prosefly/astro-theme-lotus
- Lotusshell
- Lotustokens
- Lotusconfiguration
Directory @prosefly/astro-theme-dahlia
- Dahliashell
- Dahliatokens
- Dahliaconfiguration

Keep the dependency direction visible

Both themes depend on the component package. The component package does not import either theme, inspect a theme name, or carry theme-specific branches.

That direction matters more than where the files live. If the shared layer needs to know whether it is inside Lotus or Dahlia, it has stopped being shared infrastructure and become a hidden base theme.

Instead, components expose semantic --pf-* properties with useful fallbacks. Each theme maps those roles into its own tokens. A standalone site such as Aster can do the same without adopting a documentation shell.

The practical result

An article can move between Lotus, Dahlia, and Aster without rewriting every callout, card, tab, step, or file tree.

Why not build one theme with two presets?

Presets work when the difference is mostly color and typography. Lotus and Dahlia differ in page composition, navigation density, spacing, and the relationship between the article and its surrounding controls.

Putting both behind one tree of conditions would make every shell change answer two questions: what does this feature do, and which preset is currently active? Separate theme packages keep that reasoning local. Shared content behavior is still fixed once in the component layer.

The cost is that some shell logic exists twice. That is acceptable when the duplicated code represents genuinely different products rather than an overlooked abstraction.

Use portability as a design test

Before adding a feature to the shared layer, we ask whether its meaning belongs to the document or to the shell. Before adding a theme-specific component, we ask whether an author would expect the same content to work elsewhere.

This does not produce a perfectly generic component library. It produces a focused one with a clear consumer: technical content written in Astro and MDX. That narrower contract is what lets the two themes keep distinct identities without forking the writing experience.

Building Dahlia Without Forking Lotus

Tue, 15 Sep 2026 00:00:00 GMT

The easiest way to create a second theme is to copy the first one, change the colors, and promise to clean up the duplication later. That works until a shared feature changes. Then every improvement has to be rediscovered in both codebases, while the two themes slowly develop incompatible content APIs.

Dahlia took a different path. It shares the content vocabulary and infrastructure that authors rely on, but owns the parts that make a theme feel like a product: page composition, navigation rhythm, typography, spacing, and visual hierarchy.

Begin with the reason for a second theme

Lotus is a broad documentation shell with compact navigation and a configurable product surface. Dahlia explores a quieter, content-first composition: persistent navigation on the left, a centered article, and a table of contents that supports the page without enclosing it in heavier chrome.

If the difference had been only an accent color, a preset would have been enough. The second package became worthwhile because the layout and reading rhythm were meaningfully different.

Keep shared

The docs collection contract, MDX component APIs, icon loading, Markdown transforms, code behavior, and accessible interactive primitives.

Let Dahlia own

Header and sidebar composition, article width, table of contents, search presentation, responsive transitions, typography, and palette.

Move the author contract below both themes

Callouts, cards, steps, tabs, accordions, file trees, and galleries moved into @prosefly/astro-components. The package exposes semantic CSS properties rather than importing a theme stylesheet.

Both themes depend on that package and map the same roles into their own tokens. The dependency only points one way: shared components never branch on a theme name.

A useful constraint

If a shared component needs to know which theme is rendering it, the boundary is probably in the wrong place.

Rebuild the shell from its own priorities

Rather than copying Lotus layouts and deleting pieces, Dahlia assembled its page around the reading experience it wanted.

Establish the article measure and vertical rhythm.
Place navigation and the table of contents around that article.
Add mobile transitions that preserve the same information hierarchy.
Map shared content components into Dahlia’s tokens.
Add search, i18n, code rendering, Mermaid, and theme controls as parts of the shell.

This order made the visual difference structural. It also made duplicated shell code honest: Lotus and Dahlia each own their navigation because their navigation is not the same component wearing a different class name.

Test portability with real documents

A shared contract matters only if existing content can use it. Guides containing callouts, tabs, steps, code examples, and file trees were rendered in both themes. Problems that appeared in both belonged to the shared package. Problems caused by one page composition stayed with that theme.

The result is not zero duplication. It is duplication at the product layer and reuse at the author layer—a trade that keeps each theme understandable while preserving the durable content.

Dahlia can now evolve as its own design without asking authors to rewrite the documentation that already works in Lotus.

Treating OpenAPI as Astro Content

Tue, 08 Sep 2026 00:00:00 GMT

Private package

An OpenAPI document looks like content, but it rarely behaves like a normal article. Operations share schemas, schemas refer back to one another, security rules apply at several levels, and a single endpoint may carry examples for multiple request and response media types.

Astro OpenAPI handles that complexity before the page template sees it. The package reads a specification and produces an introduction, operation entries, webhook entries, navigation, and a bounded schema model. The consuming Astro site decides what URLs to generate and how those entries fit beside the rest of its documentation.

Separate the reference model from the shell

Resolve configured sources.

Most sites load one local file. Products with several APIs can define named sources, each with a distinct base path.
Normalize author input.

OpenAPI objects become predictable operation and webhook entries with consistent method, path, security, parameter, body, response, and example data.
Bound recursive structures.

Configurable budgets limit schema depth, array items, object entries, and total nodes so the data stored in Astro’s content layer remains finite and JSON-safe.
Render inside the owning theme.

The site chooses routes and layouts, then uses API-specific components for requests, responses, security, schemas, snippets, and aside navigation.

The content collection setup remains recognizably Astro:

import { defineCollection } from 'astro:content'
import { openApiLoader, openApiSchema } from '@prosefly-pro/astro-openapi'

const api = defineCollection({
  loader: openApiLoader(),
  schema: openApiSchema(),
})

export const collections = { api }

Route ownership stays with the site

Astro OpenAPI intentionally does not inject endpoint pages. A loader can serve several routing strategies; a router embedded in the package would make every consumer inherit the same URL and layout assumptions.

Loader responsibility

Produce stable, validated entries and the navigation information needed to find them.

Theme responsibility

Decide where entries live, how they are grouped, and how the reference sits beside guides and conceptual documentation.

Lotus, for example, can place operation pages inside its existing documentation shell and combine generated API navigation with hand-authored groups. Another Astro site can choose a different base path or page composition without changing the loader.

Recursive schemas need an explicit budget

Dereferencing an OpenAPI document can produce cycles or extremely large object graphs. Passing that graph directly to a content entry makes build time and output size depend on accidental details of the source specification.

Astro OpenAPI stores a bounded display model instead. Defaults work for typical references, while projects with unusual schemas can adjust maxDepth, maxArrayItems, maxObjectEntries, and maxNodes. Hitting a budget is a visible product decision, not an unbounded traversal hidden inside a component render.

Why the boundary matters

Normalization makes the reference predictable. Route ownership keeps it composable. The schema budget keeps it safe to place in Astro’s content layer.

Components complete the model without owning the page

The package exports focused components for authentication, request bodies, response examples, schemas, webhooks, code snippets, and reference asides. Interactive pieces enhance their local section; the surrounding document remains statically rendered.

This is the useful end state: generated API reference behaves like one of the site’s content sources, not like a separate application mounted beside the documentation.

Keeping Documentation in Astro Collections

Wed, 26 Aug 2026 00:00:00 GMT

A documentation theme makes dozens of useful decisions: where navigation lives, how search opens, what an active page looks like, and how a long article behaves on a small screen. Those decisions should be easy to adopt. They should not become the only place the documentation can exist.

Prosefly themes keep source documents in Astro content collections. The theme generates routes, navigation, search metadata, and page chrome around them, but Markdown and MDX remain ordinary project files.

Directory src
- Directory content
  - Directory docs
    index.mdx
    installation.mdx
    Directory configuration
    navigation.mdx
- content.config.ts
astro.config.ts
theme.config.json

Give each layer one kind of decision

The arrangement works because three files answer three different questions.

Content collection

What fields make a valid page, where the source files live, and how Astro loads them.

Theme configuration

What the product is called, how navigation is grouped, which search provider is active, and how the shell is branded.

Markdown and MDX

What the reader needs to know, including prose, examples, and structured content components.

In Lotus, the collection boundary is explicit:

import { defineCollection } from 'astro:content'
import { docsLoader, docsSchema } from '@prosefly/astro-theme-lotus/content'

const docs = defineCollection({
  loader: docsLoader(),
  schema: docsSchema(),
})

export const collections = { docs }

The schema catches invalid frontmatter early. The loader gives the theme a predictable set of entries. Neither needs to hide the original document.

Let configuration describe the shell

theme.config.json contains product identity and navigation because those values describe how the site presents the collection. A page title and description belong to the page; the site’s logo, sidebar groups, and social links do not.

This separation keeps reviews legible. A writing change looks like a writing change. A navigation reorganization appears in one configuration diff. A visual change stays in tokens or component overrides instead of being mixed into dozens of MDX files.

Own the durable part

A theme can change. The content, URLs, and information architecture should be able to survive that change with as little rewriting as possible.

Test the boundary with a migration exercise

The simplest way to evaluate content ownership is to imagine replacing the theme.

Point a new Astro collection at the existing src/content/docs/ directory.
Map the existing frontmatter fields into the new shell.
Recreate navigation from configuration or directory structure.
Render the same Markdown and MDX through the new layouts.

Some component imports may need mapping, and shell configuration will certainly change. The article bodies, examples, headings, and Git history should not need to be exported from anywhere.

Portability still needs a contract

Keeping files in the repository does not make content automatically portable. A theme can still leak implementation details through proprietary frontmatter, layout imports, or components that only work inside one CSS environment.

That is why Prosefly pairs collections with a shared component package and semantic design tokens. The collection preserves the source; the shared author-facing contract reduces the amount that must change when the surrounding shell does.

The goal is not a perfectly theme-neutral document. It is a clean, visible boundary where the product-specific choices begin.

Defaults With an Exit

Fri, 14 Aug 2026 00:00:00 GMT

A documentation theme earns its place by resolving repetitive work: page structure, navigation, search, readable prose, responsive behavior, and accessible interaction states. A new project should feel coherent before it has a custom design system.

The same theme becomes a liability when those early decisions harden into permanent constraints. Real products eventually need their own type, color, density, navigation, and component behavior. The question is not whether a theme has opinions. It is whether the product can outgrow them without rewriting its content.

Start complete

Defaults are most useful when they form a system rather than a collection of placeholders.

A readable page

Type scale, line length, heading rhythm, code treatment, and focus states should work together on day one.

A navigable site

Desktop and mobile navigation, search, current-page state, and table of contents should already agree about the information architecture.

A responsive shell

The theme should decide how those parts collapse before every project invents a different set of breakpoints.

An incomplete default shifts design work back to the adopter while still asking them to learn the theme’s abstractions. A considered default lets the team begin with content and discover which parts actually need to become distinctive.

Put exits at meaningful layers

Not every CSS value needs a configuration option. Useful escape routes correspond to decisions a product team can name.

Tokens change the visual language.

Accent, neutrals, fonts, radius, spacing roles, and status colors establish identity without changing component structure.
Configuration changes product behavior.

Navigation, search, locale, social links, and page metadata belong to the site rather than the theme’s source code.
Component overrides change composition.

When the product genuinely needs different navigation or footer behavior, a documented component boundary is clearer than a growing collection of selectors.
Content ownership makes replacement possible.

Markdown, MDX, and Astro collections remain useful even if the shell is eventually replaced.

A useful test

Can a team begin with the theme, grow into its own visual system, and keep the same content throughout the transition?

Avoid the other extreme

An exit does not mean exposing every internal variable. A configuration surface with hundreds of unrelated values is another kind of lock-in: adopters must understand the implementation before they can make a safe change.

Semantic choices are more durable. “Accent color” expresses intent; “third link hover border” describes an accident of the current markup. A small set of roles can be applied consistently and survive component refactors.

The same rule applies to overrides. Replacing a search control is a meaningful boundary. Overriding the wrapper around every icon usually means the underlying component contract is missing the right token or prop.

The exit makes the default more trustworthy

Aster exposes centralized configuration, semantic color tokens, shared content components, and content that stays in ordinary Astro collections. Most projects will not replace every default. That is precisely why the boundaries matter: authors can begin with the complete template without betting that their needs will never change.

A strong default should feel like a useful starting point, not a decision the project is afraid to revisit.