Inline component tags

A component tag written in the page, outside any fence, renders as the real Blazor component. This is how you put a Callout between two paragraphs, a CardGrid at the end of a page, or Steps inside a section.

The pattern

Some prose.

<Callout Variant="tip" Title="Something worth knowing">
Body text with `inline code` and **emphasis**.
</Callout>

More prose.

Some prose.

More prose.

The body is markdown

An inline tag's body goes through the markdown pipeline: inline code, emphasis, links, lists, fenced code and further component tags all work. Leave a blank line between a tag and a fenced block.

<Steps>
<Step Title="Install">

```bash
dotnet tool install -g ShellDocs.CLI --prerelease
```

</Step>
<Step Title="Scaffold">
`shelldocs init MyDocs` creates a working site.
</Step>
</Steps>

This is the opposite of a razor:preview fence, whose body is Razor. The rule of thumb: a tag in the page is content, a fence is an example of code.

Self-closing tags

A tag with no body closes itself with />.

<LinkCard Title="Quick start" Description="Scaffold a fresh site." Href="/docs/getting-started/quick-start" />

Naming rules

• A tag name starts with an uppercase letter. That is how the parser tells a component from HTML: <span> stays HTML, <Span> is looked up as a component.
• Attribute values are double-quoted.
• Attribute names match the component's parameters without regard to case.

Attribute values

Values are converted to each parameter's type, the same way a fence converts them: Columns="3" becomes an int, External="true" a bool, Variant="warning" an enum member.

A quoted value can hold anything except its own quote character. Angle brackets, another tag, and text that looks like an attribute all stay inside the value:

<Callout Title="a -> b" Text='rewrites href="/" on every page' />

Three things to know:

A tag whose quote is never closed, or that runs across a blank line, is treated as plain text rather than a component.

Code spans stay code

A tag inside backticks is left alone. Writing `<Callout>` in a sentence produces inline code, not a component. The same goes for anything inside a fenced block.

Nested tags and named slots

Tags nest to any depth.

<Card Title="Outer">

<Callout Variant="info">A callout inside a card.</Callout>

</Card>

A direct child tag whose name matches one of the parent's RenderFragment parameters fills that slot instead of the default child content. See named slots.

Unknown tags

An uppercase tag that isn't a registered component is passed through as raw markup, and a warning is logged. Register the component:

builder.Services.AddShellDocs(o =>
{
    o.RegisterComponentsFromAssembly<MyMarker>();
});

When your library has the same name

If your component library registers a Card, <Card> renders yours. ShellDocs' own primitive stays reachable under a Docs prefix: <DocsCard>, <DocsCallout>, <DocsTabs>. See Documenting a component library.

Inline tag or fence

See also