You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8ccd913
Browse filesBrowse the repository at this point in the historyBrowse files
Source examples are plain four-backtick fences again, now that longer fences are read correctly. Documents longer and tilde fences, relaxes the inline attribute rules (quoted values can hold '>' and other tags), shows an inline Card with an SVG icon, and lets TypeTable rows share a name. Version strings move to 0.1.12-alpha.
Copy file name to clipboardExpand all lines: content/docs/authoring/component-tags.md
+22-16Lines changed: 22 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,19 +32,20 @@ More prose.
32
32
33
33
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.
34
34
35
-
<pre><codeclass="language-markdown"><Steps>
36
-
<Step Title="Install">
35
+
````markdown
36
+
<Steps>
37
+
<StepTitle="Install">
37
38
38
-
```bash
39
+
```bash
39
40
dotnet tool install -g ShellDocs.CLI --prerelease
40
-
```
41
+
```
41
42
42
-
</Step>
43
-
<Step Title="Scaffold">
44
-
`shelldocs init MyDocs` creates a working site.
45
-
</Step>
46
-
</Steps>
47
-
</code></pre>
43
+
</Step>
44
+
<StepTitle="Scaffold">
45
+
`shelldocs init MyDocs` creates a working site.
46
+
</Step>
47
+
</Steps>
48
+
````
48
49
49
50
This is the opposite of a [`razor:preview`](/docs/authoring/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.
50
51
@@ -68,16 +69,21 @@ A tag with no body closes itself with `/>`.
68
69
69
70
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.
70
71
71
-
Keep inline attribute values to plain text:
72
+
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:
73
+
74
+
```markdown
75
+
<CalloutTitle="a -> b"Text='rewrites href="/" on every page' />
76
+
```
77
+
78
+
Three things to know:
72
79
73
80
<TypeTable>
74
-
<TypeRowName="Angle brackets"Type="avoid"Description="The tag ends at the first closing angle bracket, so a value containing one cuts the tag short and the component is dropped." />
75
-
<TypeRowName="HTML entities"Type="avoid"Description="Entities are not decoded. They show up as typed." />
76
-
<TypeRowName="Backticks"Type="avoid"Description="Attribute text is not markdown. Backticks show up as typed." />
77
-
<TypeRowName="Escaped quotes"Type="avoid"Description="There is no escape for a double quote inside a value. Rephrase, or use single quotes in the text." />
81
+
<TypeRowName="Quotes"Type="choose"Description="There is no escape for a quote inside a value. Wrap the value in single quotes when it contains double quotes, and the other way round." />
82
+
<TypeRowName="Markdown"Type="literal"Description="Attribute text is not markdown. Backticks and asterisks show up as typed. Put formatted text in the tag body." />
83
+
<TypeRowName="HTML entities"Type="literal"Description="Entities are not decoded. Write the character itself." />
78
84
</TypeTable>
79
85
80
-
When a value needs any of those, move the content into the tag body, or write the example as a `razor:preview` fence, where raw markup in attributes is fine.
86
+
A tag whose quote is never closed, or that runs across a blank line, is treated as plain text rather than a component.
@@ -62,9 +64,31 @@ Four-space-indented code blocks still work (CommonMark supports them) but you lo
62
64
63
65
Backtick-wrapped inline code (`` `like this` ``) is styled but has no copy button or language handling. Use it for identifiers, short snippets, and API references : `<Callout>`, `AddShellDocs()`, `Program.cs`.
64
66
65
-
## Interactions with other markdown
67
+
## Longer fences and tildes
68
+
69
+
A fence is three or more backticks, closed by a run at least as long. Inside it everything is verbatim : no markdown parsing, no component tags, no previews.
70
+
71
+
To show a fence as an example, as this page does, wrap it in a longer one:
72
+
73
+
`````markdown
74
+
````markdown
75
+
```csharp
76
+
varx=1;
77
+
```
78
+
````
79
+
`````
80
+
81
+
Tilde fences work the same way and save counting backticks:
82
+
83
+
````markdown
84
+
~~~markdown
85
+
```razor:preview
86
+
<Callout>Shown as source, not rendered.</Callout>
87
+
```
88
+
~~~
89
+
````
66
90
67
-
Inside a fence, the content is **verbatim** : no markdown parsing, no HTML entity handling. You can put anything inside : Razor tags, JSX, YAML, another fence's opening marker. The parser handles nested backtick counts via CommonMark's rule (outer fence needs one more backtick than any inner sequence).
91
+
A component tag or a `razor:preview` fence inside a longer fence stays literal, and whatever follows the block on the page renders normally.
@@ -95,21 +119,6 @@ For panels that are not code, use [Tabs](/docs/components/tabs).
95
119
96
120
Full docs: [CodeGroup](/docs/components/code-group).
97
121
98
-
## Showing a fence as an example
99
-
100
-
To show the markdown for a fence, as this page does, don't nest it in a longer fence. ShellDocs scans for three-backtick fences before markdown is parsed, and a four-backtick block that contains one puts the scanner out of step: the next `razor:preview` on the page renders as plain code.
101
-
102
-
Write the example as an HTML code block instead, with the backticks and angle brackets as entities:
Copy file name to clipboardExpand all lines: content/docs/authoring/index.md
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,8 @@ Everything ShellDocs asks of you as an author lives here : the frontmatter field
12
12
13
13
A ShellDocs page is a `.md` file under `content/`. Drop one in, it appears in the sidebar automatically : no registration, no import, no meta.json edit required.
Copy file name to clipboardExpand all lines: content/docs/components/card.md
+6-4Lines changed: 6 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,9 +38,11 @@ Pass raw SVG markup as `IconSvg`. It renders inside a `.doc-card-icon` container
38
38
39
39
Write the SVG with single-quoted attributes so it fits inside the double-quoted `IconSvg` value.
40
40
41
-
<CalloutVariant="warning"Title="Icons belong in a preview fence or a .razor page">
42
-
Raw SVG in an attribute works inside a `razor:preview` fence and in `.razor` files. An inline `Card` tag in page prose can't carry it : the prose tag scanner ends a tag at the first closing angle bracket, and HTML entities are not decoded. For a card grid with icons in prose, build it as a small Razor component and drop that in.
43
-
</Callout>
41
+
The same attribute works on a `Card` written straight into the page:
Use the inline form for real walk-throughs. Keep `razor:preview` for showing the component itself : fence bodies are Razor, so markdown inside them renders literally.
0 commit comments