Skip to content

Latest commit

 

History

History
172 lines (132 loc) · 5.79 KB

markdown.md

File metadata and controls

172 lines (132 loc) · 5.79 KB

Markdown

Astro docs: Markdown

.md and .mdx files are handled by Astro exactly as usual. What changes is that C# can supply Markdown, and get Astro's own pipeline applied to it.

In TypeScript

A loader hands Astro raw Markdown and Astro renders it:

loader: {
  name: 'my-loader',
  async load({ store, renderMarkdown }) {
    store.set({ id: 'hello', data: { title: 'Hello' }, rendered: await renderMarkdown('## Hi') });
  },
}

In C#

Return a raw Body and the same thing happens — AstroSharp calls renderMarkdown for you:

new ContentEntry
{
    Id = "hello",
    Data = new { title = "Hello" },
    Body = "## Introduction\n\nRendered by **Astro's** own pipeline.",
}

You get your markdown config, remark and rehype plugins, and syntax highlighting — so render(entry) and <Content /> behave exactly as they would for a globbed .md file. Headings and their slugs are extracted automatically.

No Markdown engine in C#, and no configuration.

Rendering it yourself

Set Rendered instead when you want full control — with a Markdown library from NuGet, say, or to emit non-Markdown HTML:

new ContentEntry
{
    Id = "why-csharp",
    Data = new { title = "Why C#" },
    Rendered = new RenderedContent
    {
        Html = "<h2 id=\"why\">Why C#</h2><p>Because the BCL is <strong>excellent</strong>.</p>",
        Metadata = new RenderedMetadata
        {
            Headings = [new ContentHeading { Depth = 2, Slug = "why", Text = "Why C#" }],
        },
    },
}

When Rendered is set it takes precedence and no Markdown pass runs.

Reading it back

From an .astro page, render(entry) and <Content /> work normally. From C# the HTML comes across as entry.Html:

@((MarkupString)entry.Html!)

There is no <Content /> component to hand back — a component instance would not survive the process boundary. Headings are on entry.Headings.

render(entry)'s third member is there too. A remark plugin that writes to the frontmatter — Astro's reading-time recipe is the canonical one — puts its result somewhere the collection's schema never declared, so it is not on Data:

---
const { remarkPluginFrontmatter } = await render(entry);
---
<p>{remarkPluginFrontmatter.minutesRead}</p>
<p>@entry.RemarkPluginFrontmatter.Get<int>("minutesRead")</p>

A loader that sets Rendered itself fills the same slot with RenderedContent.Metadata.Frontmatter, so a C#-rendered entry can carry one too.

A Markdown page in a C# layout

The other direction: a .md page's layout: frontmatter may name a .razor file, and Astro's Markdown layout contract applies unchanged.

---
layout: ../layouts/Post.astro
title: A Markdown page
---
@* src/layouts/Post.razor *@
@code {
    [Parameter] public Frontmatter? Frontmatter { get; set; }
    [Parameter] public IReadOnlyList<Heading> Headings { get; set; } = [];
    [Parameter] public string? Url { get; set; }
    [Parameter] public string? File { get; set; }
    [Parameter] public string? RawContent { get; set; }
    [Parameter] public string? CompiledContent { get; set; }
    [Parameter] public RenderFragment? ChildContent { get; set; }

    public sealed class Frontmatter { public string? Title { get; set; } }
    public sealed class Heading
    {
        public int Depth { get; set; }
        public string? Slug { get; set; }
        public string? Text { get; set; }
    }
}

<h1>@Frontmatter?.Title</h1>
<main>@ChildContent</main>

The rendered Markdown arrives as the default slot, so @ChildContent is the <slot /> an .astro layout writes. Frontmatter, Headings, Url and File are ordinary props.

The two function props

rawContent() and compiledContent() are functions in Astro's contract, and a function cannot cross to C# as itself. Both are called before the render, so what a [Parameter] public string? receives is an ordinary string — one you can measure, slice and test like any other:

@if (RawContent!.Length > 500) { <p>A long post</p> }

compiledContent() is HTML rather than text, so cast it rather than writing it plainly, which would escape it:

<article>@((MarkupString)(CompiledContent ?? ""))</article>

Calling them early rather than substituting them afterwards is deliberate: both are pure reads over content Astro has already produced by the time the layout renders, so there is nothing to save by being lazy and a whole class of ordinary C# to lose. A function prop Astro does not define — one your own .astro page passes — is treated the other way round; see Components.

Limitations

compiledContent() on an .mdx page has nothing to give. Astro's own version throws there; here the prop is left unset, so CompiledContent is null. The slot (ChildContent) is the rendered content either way, and is what a layout usually wants.

.mdx importing a .razor component is untested. A .razor file does compile to a real server module — that is how an .astro file imports one — so there is no obvious reason it would fail, and the renderer dispatches on the component value rather than on the importing file's type. Nothing in the suite exercises it, so it is recorded as unverified rather than claimed to work.

An entry with neither Body nor Rendered has nothing to render, exactly as in Astro.

Astro 7 changed the default pipeline to its own Sätteri processor rather than remark/rehype. A loader's raw Body goes through whatever Astro's pipeline currently is, so a C#-sourced collection picks up that change with everything else — including the GitHub-Flavored Markdown and SmartyPants behaviour. A loader that sets Rendered is unaffected.