← 全部文章

你会用到的 Markdown

主题所样式化正文元素的简短参考。标题、链接、列表、表格、代码、标注框。

把本文当作正文表面的速查表。开两个窗口:一边看源码,一边看渲染结果。

标题#

文章从 ## 开始。页面标题是唯一的 h1。

## Section
### Subsection

行内文本#

主题会样式化这些行内元素:

A [link](https://astro.build), **bold**, _italic_, `inline code`,
<kbd>⌘</kbd> + <kbd>K</kbd>, and <mark>highlighted</mark> text.

渲染为:

一条 链接、粗体、斜体、行内代码、⌘ + K,以及 高亮 文本。

在段落内用 <mark> 标出需要留意的短语。整段提示请用标注框。

列表#

顺序重要时用有序列表,否则用无序列表。

1. First step.
2. Second step.
3. Third step.
- One useful example
- One clear tradeoff
- One next step

嵌套列表可用,但尽量保持浅层:

  • 章节
    • 小节
    • 另一小节
  • 章节

引用#

块引用被样式化为停顿,而非一般强调。

> A writing surface should disappear while the reader moves through it.

写作界面应在读者阅读时隐去自身。

带来源:

> Don't communicate by sharing memory, share memory by communicating.<br>
> — <cite>Rob Pike</cite>

不要通过共享内存来通信,要通过通信来共享内存。
— Rob Pike

表格#

用于紧凑的参考数据:

| Element | Use |
| ------- | ----------------------------- |
| Heading | Structure the article |
| Quote | Pause on a specific idea |
| Code | Show exact commands or values |
元素用途
标题组织文章结构
引用在某一点上稍作停顿
代码展示精确命令或取值

若表格需要排序或交互,请移到文章外。

代码块#

务必标明语言。高亮由 astro-expressive-code 提供,使用内置的 tone-cold 主题。

```ts
const site = { title: 'Tone' };
```

渲染为:

const site = { title: 'Tone' };

终端:

Terminal window
npm run build

JSON 配置:

{
"buildCommand": "npm run build",
"outputDirectory": "dist"
}

Astro 组件使用同一套表面样式:

---
const title = 'Quiet defaults';
---
<section class="intro">
<h2>{title}</h2>
<slot />
</section>

图片#

用相对路径从 src/assets/ 引用图片。Astro 在构建时处理(缩放、AVIF/WebP、在标记中输出尺寸)。

![Description for screen readers](../../../assets/tone-sample-blue-architecture.jpg)
_Optional caption goes here._

供屏幕阅读器使用的描述 可选说明文字写在这里。

在渲染后的文章中点击图片可打开灯箱。紧跟图片后的 _斜体_ 文字会被当作说明。

标注框#

纯 HTML 加 class。主题提供三种色调:

<div class="callout callout-note">
<p>Use for extra context.</p>
</div>
<div class="callout callout-tip">
<p>Use for a small recommendation.</p>
</div>
<div class="callout callout-warning">
<p>Use for limits or likely mistakes.</p>
</div>

用于补充背景信息。

用于小建议。

用于限制条件或常见失误。

可用的行内 HTML#

<abbr title="Cascading Style Sheets">CSS</abbr>
H<sub>2</sub>O · x<sup>2</sup>
Press <kbd>Esc</kbd>

CSS 是承载大部分视觉系统的语言。H2O 与 x2 在行内读起来很自然。按 Esc 可关闭主题中任何打开的对话框。

分隔线#

只有章节分隔需要比标题更强的力度时才用分隔线。

---

脚注#

The first half of the work is easy.[^1]
[^1]: The second half is what actually ships.

前半部分的工作很容易。1

脚注保持简短。若注释超过一句,请写进正文。

主题不样式化的内容#

若在标注框外使用 <details>、<summary> 或 <aside>,会应用浏览器默认样式。可在 src/styles/prose.css 添加自己的 CSS,或用 MDX 组件包裹该元素。

Footnotes#

  1. 后半部分才是真正要交付的。 ↩