|
| 1 | +--- |
| 2 | +title: Code tabs on previews |
| 3 | +description: Replace a preview's Code panel with tabs you write, switch them together across the site, and add a page-level switch and a caption. |
| 4 | +order: 13 |
| 5 | +--- |
| 6 | + |
| 7 | +# Code tabs on previews |
| 8 | + |
| 9 | +A preview's Code panel normally shows the Razor that rendered it. Put `<CodeTab>` children inside the preview and the panel shows those instead, one tab each. Use it when the reader's code isn't the code that drew the example : the same result in two syntaxes, or one live example documented for several platforms. |
| 10 | + |
| 11 | +<SyncSwitch SyncKey="syntax" Options="Markdown, Razor" /> |
| 12 | + |
| 13 | +<DemoPreview Component="PackageFamilyDemo" Layout="stretch" SyncKey="syntax" Caption="Rendered with Blazor"> |
| 14 | +<CodeTab Label="Markdown"> |
| 15 | + |
| 16 | +```markdown |
| 17 | +<CardGrid Columns="2"> |
| 18 | +<Card Title="ShellDocs.Components" Description="Layouts, chrome and the content primitives." /> |
| 19 | +<Card Title="ShellDocs.Markdown" Description="The Markdig pipeline and component slots." /> |
| 20 | +<Card Title="ShellDocs.Core" Description="Navigation graph and search index." /> |
| 21 | +<Card Title="ShellDocs.Tokens" Description="Design tokens as CSS variables." /> |
| 22 | +</CardGrid> |
| 23 | +``` |
| 24 | + |
| 25 | +</CodeTab> |
| 26 | +<CodeTab Label="Razor"> |
| 27 | + |
| 28 | +```razor |
| 29 | +<CardGrid Columns="2"> |
| 30 | + @foreach (var package in Packages) |
| 31 | + { |
| 32 | + <Card Title="@package.Name" Description="@package.Summary" /> |
| 33 | + } |
| 34 | +</CardGrid> |
| 35 | +``` |
| 36 | + |
| 37 | +</CodeTab> |
| 38 | +</DemoPreview> |
| 39 | + |
| 40 | +Written as: |
| 41 | + |
| 42 | +````markdown |
| 43 | +<DemoPreview Component="PackageFamilyDemo" Layout="stretch" SyncKey="syntax" Caption="Rendered with Blazor"> |
| 44 | +<CodeTab Label="Markdown"> |
| 45 | + |
| 46 | +```markdown |
| 47 | +<CardGrid Columns="2"> |
| 48 | +<Card Title="ShellDocs.Components" Description="Layouts, chrome and the content primitives." /> |
| 49 | +</CardGrid> |
| 50 | +``` |
| 51 | + |
| 52 | +</CodeTab> |
| 53 | +<CodeTab Label="Razor"> |
| 54 | + |
| 55 | +```razor |
| 56 | +<CardGrid Columns="2"> |
| 57 | + @foreach (var package in Packages) |
| 58 | + { |
| 59 | + <Card Title="@package.Name" Description="@package.Summary" /> |
| 60 | + } |
| 61 | +</CardGrid> |
| 62 | +``` |
| 63 | + |
| 64 | +</CodeTab> |
| 65 | +</DemoPreview> |
| 66 | +```` |
| 67 | + |
| 68 | +## The rules |
| 69 | + |
| 70 | +- Each tab's code is the first fence inside it. The fence's language drives highlighting. |
| 71 | +- Without a fence, the tag's text is the code and `Language="…"` sets the language. |
| 72 | +- The **Copy** button copies the tab that is showing. |
| 73 | +- Without `<CodeTab>` children the Code panel shows the Razor source, as before. |
| 74 | + |
| 75 | +## Where they work |
| 76 | + |
| 77 | +<TypeTable> |
| 78 | +<TypeRow Name="DemoPreview" Type="yes" Description="The tabs replace the demo's .razor file in the Code panel." /> |
| 79 | +<TypeRow Name="ComponentPreview" Type="yes" Description="The tabs are taken out of the body before it is passed to the component as child content." /> |
| 80 | +<TypeRow Name="IframePreview" Type="yes" Description="Without tabs an iframe preview has no Code panel at all." /> |
| 81 | +<TypeRow Name="razor:preview fence" Type="no" Description="The fence body is Razor, so a code fence can't sit inside it. Use DemoPreview instead." /> |
| 82 | +</TypeTable> |
| 83 | + |
| 84 | +## Switching together |
| 85 | + |
| 86 | +`SyncKey` works as it does on [`CodeGroup`](/docs/components/code-group) and [`Tabs`](/docs/components/tabs). Every block with the same key switches together, on this page and on later ones, and the choice is saved in `localStorage`. |
| 87 | + |
| 88 | +## A missing tab |
| 89 | + |
| 90 | +When a block has no tab for the current choice it says so and keeps its height, instead of jumping to another tab. Choose **Razor** in the first example, then look at this one: |
| 91 | + |
| 92 | +<DemoPreview Component="PackageFamilyDemo" Id="family-markdown-only" Layout="stretch" SyncKey="syntax"> |
| 93 | +<CodeTab Label="Markdown"> |
| 94 | + |
| 95 | +```markdown |
| 96 | +<CardGrid Columns="2"> |
| 97 | +<Card Title="ShellDocs.Components" Description="Layouts, chrome and the content primitives." /> |
| 98 | +</CardGrid> |
| 99 | +``` |
| 100 | + |
| 101 | +</CodeTab> |
| 102 | +</DemoPreview> |
| 103 | + |
| 104 | +## Page switch |
| 105 | + |
| 106 | +A page switch is a row of tabs on the page itself that drives a `SyncKey`. The **Markdown | Razor** row at the top of this page is one. Declare it once and it appears on every page whose blocks use that key: |
| 107 | + |
| 108 | +```csharp |
| 109 | +builder.Services.AddShellDocs(o => |
| 110 | +{ |
| 111 | + o.AddSyncSwitch("platform", "MAUI", "Avalonia"); |
| 112 | +}); |
| 113 | +``` |
| 114 | + |
| 115 | +It sits under the page header when `RenderPageTitle` is on, otherwise right above the first block that uses the key. Pages that don't use the key don't get one. The first option is the default until a reader picks another, so every block starts on the same tab. |
| 116 | + |
| 117 | +To choose the spot yourself, write the tag. The automatic one is then left out on that page: |
| 118 | + |
| 119 | +```markdown |
| 120 | +<SyncSwitch SyncKey="platform" /> |
| 121 | +``` |
| 122 | + |
| 123 | +For a key with no `AddSyncSwitch`, list the options on the tag. This page does that: |
| 124 | + |
| 125 | +```markdown |
| 126 | +<SyncSwitch SyncKey="syntax" Options="Markdown, Razor" /> |
| 127 | +``` |
| 128 | + |
| 129 | +<TypeTable> |
| 130 | +<TypeRow Name="SyncKey" Type="string" Default="—" Required="true" Description="The key the switch drives." /> |
| 131 | +<TypeRow Name="Options" Type="string?" Default="from AddSyncSwitch" Description="Comma-separated option labels. They must match the tab labels." /> |
| 132 | +</TypeTable> |
| 133 | + |
| 134 | +## Caption |
| 135 | + |
| 136 | +`Caption` adds a short muted note to the preview's toolbar, such as which platform rendered the example. The first preview on this page has one. |
| 137 | + |
| 138 | +```markdown |
| 139 | +<DemoPreview Component="PackageFamilyDemo" Caption="Rendered with Blazor" /> |
| 140 | +``` |
| 141 | + |
| 142 | +`ShellDocsOptions.PreviewCaption` sets a caption for every preview on the site. A preview's own `Caption` replaces it. |
| 143 | + |
| 144 | +```csharp |
| 145 | +o.PreviewCaption = "Rendered with Blazor"; |
| 146 | +``` |
| 147 | + |
| 148 | +## From a Razor file |
| 149 | + |
| 150 | +Outside markdown, pass the tabs as a parameter: |
| 151 | + |
| 152 | +```razor |
| 153 | +<DemoPreview Component="PackageFamilyDemo" |
| 154 | + SyncKey="syntax" |
| 155 | + CodeTabs="@(new PreviewCodeTab[] { new("Markdown", markdownSource, "markdown") })" /> |
| 156 | +``` |
| 157 | + |
| 158 | +A `PreviewCodeTab` is a label, the code, and a language that defaults to `text`. |
| 159 | + |
| 160 | +## XAML |
| 161 | + |
| 162 | +`xaml` and `axaml` fences are highlighted as XML. Sites created before `0.1.13-alpha` need `'xml'` in the `langs` list of the Shiki loader in `App.razor`. |
| 163 | + |
| 164 | +## Props |
| 165 | + |
| 166 | +These are the same on `DemoPreview`, `ComponentPreview` and `IframePreview`. |
| 167 | + |
| 168 | +<TypeTable> |
| 169 | +<TypeRow Name="SyncKey" Type="string?" Default="—" Description="Blocks with the same key switch together and remember the choice." /> |
| 170 | +<TypeRow Name="Caption" Type="string?" Default="PreviewCaption" Description="Muted note in the toolbar." /> |
| 171 | +<TypeRow Name="CodeTabs" Type="IReadOnlyList<PreviewCodeTab>?" Default="—" Description="The tabs, when the preview is written in a .razor file." /> |
| 172 | +</TypeTable> |
| 173 | + |
| 174 | +`CodeTab` inside a preview: |
| 175 | + |
| 176 | +<TypeTable> |
| 177 | +<TypeRow Name="Label" Type="string" Default="—" Required="true" Description="Tab label, and the value a SyncKey matches on." /> |
| 178 | +<TypeRow Name="Language" Type="string?" Default="text" Description="Highlighting language when the body has no fence." /> |
| 179 | +</TypeTable> |
| 180 | + |
| 181 | +## See also |
| 182 | + |
| 183 | +<CardGrid Columns="2"> |
| 184 | +<LinkCard Title="DemoPreview" Description="The preview these tabs most often sit in." Href="/docs/components/demo-preview" /> |
| 185 | +<LinkCard Title="IframePreview" Description="A live example from another page, with the same tabs." Href="/docs/components/iframe-preview" /> |
| 186 | +</CardGrid> |
0 commit comments