Post-processing rendered Markdown HTML
Widely compatibleRendering:Prerendered: WorksOn-demand: WorksAstro>=5.0.0
Works across all listed Astro environments.
When you load a Markdown entry from a Content Collection, entry.rendered.html looks like the easiest way to grab its HTML string for custom post-processing—such as rewriting links, stripping tags, injecting wrapper markup, or running a per-page rehype transform.
However, entry.rendered.html contains intermediate markup from before Astro’s <Content /> component resolves local and remote images. Any optimized Markdown image still carries an internal __ASTRO_IMAGE_ placeholder attribute instead of a final src and srcset, so rendering or transforming entry.rendered.html directly leaves you with broken images.
To get the exact, fully processed HTML that <Content /> produces, render <Content /> first and capture its output.
Option 1: Capture <Content /> with a slot wrapper component
Section titled “Option 1: Capture <Content /> with a slot wrapper component”In an Astro page or layout, create a small wrapper component that renders its default slot into a string using Astro.slots.render('default'), runs your post-processing logic, and emits the transformed HTML via <Fragment set:html={...} />:
---import { rehype } from "rehype";
interface Props { transform?: (html: string) => string | Promise<string>;}
const rawHTML = await Astro.slots.render("default");
// Example: post-process the rendered HTML fragment with rehypeconst processedHTML = Astro.props.transform ? await Astro.props.transform(rawHTML) : String( await rehype() .data("settings", { fragment: true }) // .use(yourRehypePlugin) .process(rawHTML), );---
<Fragment set:html={processedHTML} />Then wrap <Content /> inside <ProcessHTML> in your page:
---import { getEntry, render } from "astro:content";import ProcessHTML from "../../components/ProcessHTML.astro";
const entry = await getEntry("blog", Astro.params.slug!);if (!entry) return Astro.redirect("/404");
const { Content } = await render(entry);---
<article> <ProcessHTML> <Content /> </ProcessHTML></article>Because <Content /> runs inside Astro’s normal component renderer before Astro.slots.render("default") returns, all local and remote Markdown images are already resolved to their final optimized <img> tags with src, width, height, and srcset.
Option 2: Render to a string outside .astro templates
Section titled “Option 2: Render to a string outside .astro templates”If you need faithful HTML inside an API endpoint (such as an RSS feed or search index generator) where you can’t wrap <Content /> in a .astro component, use Astro’s experimental Container API:
import { type CollectionEntry, render } from "astro:content";import { experimental_AstroContainer as AstroContainer } from "astro/container";
export async function renderEntryHTML(entry: CollectionEntry<"blog">) { const container = await AstroContainer.create(); const { Content } = await render(entry); return await container.renderToString(Content);}You can then pass the returned HTML string into rehype, a sanitizer, or an RSS feed serializer with all Astro image assets intact.
Things to keep in mind
Section titled “Things to keep in mind”- Prefer build-time Markdown plugins when possible: If your transformation doesn’t depend on resolved
/_astro/...image URLs or per-request runtime context, a SätterihastPluginsorrehypePluginstransform runs once at compile time and avoids parsing HTML a second time. - Sanitize untrusted transformations:
set:htmlinjects raw HTML without escaping. Only pass trusted HTML or output that has been sanitized. - Slot buffering: Calling
await Astro.slots.render("default")buffers the entire slot in memory before streaming it to the client. For standard Markdown articles this overhead is negligible, but avoid wrapping an entire page layout in a slot-rendering component.
Source discussion
Section titled “Source discussion”Compatibility
| Environment | Support | Version |
|---|---|---|
| Framework | ||
| Astro | Works | >=5.0.0 |
| RenderingAstro docs | ||
| Prerendered | Works | Any version |
| On-demand | Works | Any version |