Markdown 与 MDX

最小文章

inkstack new --format md --slug plain-note --title "普通笔记"

生成 content/markdown-posts/plain-note/index.md。规范元数据只来自 YAML front matter：

---
title: 普通笔记
slug: plain-note
description: 用于列表、RSS 与 SEO 的摘要。
date: '2026-10-07'
tags: [笔记]
status: draft
visibility: public
language: zh-CN
---

## 第一节

这是文章正文。

![图片说明](assets/diagram.svg)

页面布局输出唯一 h1；正文使用 ## 到 ####。创建在仓库内的文章不要再写一级标题。外部导入器可以把首个一级标题提取为元数据。

支持的语法

Markdown 通过 unified / remark / rehype 处理，支持 GFM 表格、任务列表、脚注、KaTeX 公式与 Shiki 代码高亮。

行内公式：$E = mc^2$

块公式：
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

脚注引用[^note]。

[^note]: 脚注正文。

代码围栏尽量声明语言。代码块的复制、表格的局部横向滚动、图片灯箱与脚注展示均来自共享主题。普通 Markdown 不接受原始 HTML，也不通过放宽 sanitizer 来接纳脚本。

图片与链接

图片保存在文章自身的 assets/，使用相对路径；不能直接引用本机绝对路径或用 ../ 越界。导入现有 Markdown 时，inline 图片、引用式图片和 cover 均可由导入器自动迁移。

文章 slug 在 Typst、Markdown、MDX 之间共享命名空间。标签支持中文、C# 和 C++，不要手写编码后的标签 URL。标签不允许 %、路径分隔符或独立的 . / ..。

MDX 组件

MDX 在同样的元数据与文章 UI 上增加受信任组件和表达式：

import Callout from '@inkstack/theme/components/Callout.astro'

export const demoCount = 3

## 组件示例

<Callout type="tip" title="提示">共 {demoCount} 项。</Callout>

title、slug、日期、标签、发布状态和 frontmatter 等保留导出不能覆盖 YAML。正文目录仅收录静态 Markdown 标题，不从组件的动态标题生成目录。复杂组件用 .not-prose 隔离文章样式。

信任边界

MDX 不执行普通 Markdown sanitizer，因为它本来就是构建代码。仓库维护者应审查 import、依赖与脚本，不从上传、CMS 或网络动态编译 MDX。自动外部文件导入仅支持 .md 与 .typ；组件文章请在仓库内创建。详见安全与信任。