Skip to content

Post-processing rendered Markdown HTML

Widely compatibleRendering:Prerendered: WorksOn-demand: WorksAstro>=5.0.0

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={...} />:

src/components/ProcessHTML.astro
---
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 rehype
const 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:

src/pages/blog/[...slug].astro
---
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:

src/lib/render-entry-html.ts
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.

  • 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ätteri hastPlugins or rehypePlugins transform runs once at compile time and avoids parsing HTML a second time.
  • Sanitize untrusted transformations: set:html injects 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.

Compatibility

EnvironmentSupportVersion
Framework
AstroWorks>=5.0.0
RenderingAstro docs
PrerenderedWorksAny version
On-demandWorksAny version
Compatibility legend:Recommended — Best practiceWorks — SupportedDoesn't work — Unsupported