Sample 01 — Rich Writing and Reader Conversations

Good writing gives the reader a clear path through an idea. Components help when they have a specific job: a warning before a risky step, an optional explanation, or a question worth discussing. This sample shows the source first and the rendered result immediately afterward.

The examples describe an imaginary note-taking workflow. Adapt the words as well as the syntax. Begin with ordinary headings, paragraphs, lists, and links; add the components below when they make the explanation easier to use.

Emphasize a phrase, not a paragraph

Use bold for a central idea, italics for a qualification, and a highlight for a small detail that deserves a second look. The two highlight forms below have the same reading purpose.

1
Keep **one clear question** in view. Record *what you observed* before explaining it.
2

3
==A **specific** change== is more useful than :mark[a vague impression].

Keep one clear question in view. Record what you observed before explaining it.

A specific change is more useful than a vague impression.

Highlight markers stay on one line, directly beside their content. In code, ==literal text== remains literal.

Choose a callout by its meaning

These five callouts share the same Markdown container shape. Their labels tell the reader what kind of attention the information needs.

1
:::note[Context]
2
This notebook describes a small example, not a completed study.
3
:::
4

5
:::tip[Make the next step easy]
6
Finish a session with one question you can investigate tomorrow.
7
:::
8

9
:::important[Keep the original]
10
Preserve the source data before making a summary.
11
:::
12

13
:::warning[Check the destination]
14
A local link must point to published content before publication.
15
:::
16

17
:::caution[Review a destructive action]
18
Read the selected filenames before permanently removing anything.
19
:::

GitHub-style alerts are another convenient spelling for a short callout:

1
> [!TIP]
2
> Put the explanation next to the step that needs it.

Use callouts sparingly in a real article. Their meaning becomes easier to notice when most of the page remains ordinary prose.

Let optional detail fold away

A disclosure keeps a longer explanation available without making it a prerequisite for the next sentence. It works as a native expandable section even without JavaScript.

1
:::details[Why separate observations from explanations?]
2
An observation records what happened. An explanation proposes why.
3

4
- Observation: the example took three steps.
5
- Explanation: the shorter route may have reduced the work.
6

7
Keeping the two separate makes the proposal easier to test.
8
:::

Present a procedure as steps

Use an ordered list inside steps. Each item should describe one action, with its purpose close by.

1
:::steps
2
1. **Ask.** Write a question that can be answered by an example.
3
2. **Try.** Change one thing and record the result.
4
3. **Reflect.** Explain what the result supports and what remains uncertain.
5
:::

A task list is useful for tracking preparation rather than explaining a sequence:

• State the question.
• Label illustrative data.
• Replace the example with your own material.

Offer two useful views with tabs

Rich tabs contain ordinary Markdown, including lists, links, and math. The outside fence uses four colons because its panels use three. Keep each panel meaningful on its own; all panels remain available in the static fallback.

1
::::tabs
2
:::tab[Explanation]
3
Keep a session small enough to **finish and reflect on**.
4
:::
5

6
:::tab[Checklist]
7
- Choose one question.
8
- Record one example.
9
- Write one next step.
10
:::
11
::::

Try it: switch panels, then use the arrow keys while a tab has focus. Rich tabs are the right choice when the panel needs formatted text; a plain-text interactive tab widget is useful for shorter unformatted summaries.

Pair an authored question with an answer

Question and answer components are part of the article itself. They do not create a reader discussion thread.

1
:::question[Must every section use a component?]
2
Would this paragraph be clearer as plain prose?
3
:::
4

5
:::answer[Start with the sentence]
6
Usually, yes. Add a component only when its structure helps the reader do something.
7
:::

Keep small notation readable

Keyboard keys, abbreviations, subscripts, and superscripts have dedicated inline forms. Use semantic notation instead of changing font sizes by hand.

1
Press :kbd[Ctrl] + :kbd[F] to find a phrase. An :abbr[SVG]{title="Scalable Vector Graphics"}
2
illustration stays sharp when enlarged. Write H:sub[2]O or x:sup[2] for simple text notation.

Press Ctrl + F to find a phrase. An SVG illustration stays sharp when enlarged. Write H₂O or x² for simple text notation.

Use $...$ when the expression needs mathematical layout: .

Add a definition and a footnote

Definitions belong near a term's first use. A footnote holds a useful aside without interrupting the main argument.¹

1
Observation
2
: A description of something noticed or recorded.
3

4
Model
5
: An explicit account used to explain a relationship or make a prediction.
6

7
A footnote keeps supporting detail nearby.[^sample-context]
8

9
[^sample-context]: This is an authored footnote, not a reader annotation.

Observation

A description of something noticed or recorded.

Model

An explicit account used to explain a relationship or make a prediction.

Invite a reader conversation

A discussion section can connect a particular question to Giscus. Give it a stable label and retain that label when revising the wording.

1
:::discussion[What makes a note useful later?]{#sample-useful-note comments="true"}
2
Which detail would you add so a future reader could repeat the example?
3
:::

Once the article is published with discussions configured, readers can open its conversation. Private draft previews show the discussion's placement without posting anything to GitHub.

Readers can also use the article's right-edge annotation control to discuss an exact rendered line. Existing threads appear as badges and in the Annotations tabs of the outline and conversation panel. These reader-created annotations are separate from authored footnotes and Q&A.

Point to a useful next destination

A link card gives a destination a short description. It is still a normal link, so its target must exist.

1
::link-card[Explore the archive]{href="/archive/" description="Published posts and articles, arranged over time."}

When adapting this sample, begin with the paragraphs, then keep only the components that make those paragraphs easier to use.