半神主题短代码完整使用指南

Demius2026/9/13大约 6 分钟主题开发Astro主题Shortcode写作

半神的短代码兼容 Hugo / Handsome 风格写法，适合在 Markdown 文章里插入更丰富的正文组件。基础格式如下：

{{< shortcode attr="value" >}}
{{< /shortcode >}}

有内容包裹时使用成对写法；没有内容时使用单行写法。

优先使用 Markdown 原生能力写普通内容，只有在需要折叠、选项卡、媒体嵌入、下载卡片等特殊展示时再使用短代码。

总览

类型	短代码
提示块	`note`、`tip`、`info`、`success`、`warning`、`danger`、`alert`、`callout`
折叠和隐藏	`collapse`、`details`、`secret`、`encrypt`、`reply-visible`
内容容器	`card`、`box`、`quote`
交互排版	`tabs`、`tab`、`timeline`、`timeline-item`
链接和按钮	`button`、`btn`、`linkcard`、`link`、`download`、`netdisk`、`pan`、`github`、`douban`
图片	`image`、`picture`、`livephoto`、`gallery`
视频和网页	`bilibili`、`youtube`、`video`、`douyin`、`iframe`、`embed`
音乐和音频	`audio`、`music`、`aplayer`、`netease`、`music163`
行内样式	`badge`、`color`

提示块

提示块适合放注意事项、结论、警告和补充说明。

这是 info 类型，适合放背景信息。

这是 success 类型，适合放完成结果。

这是 warning 类型，适合放操作前提醒。

{{< note title="提示" >}}
这里是提示内容。
{{< /note >}}

{{< warning title="注意" >}}
这里是警告内容。
{{< /warning >}}

也可以使用 ::: 指令写法：

:::tip title="建议"
这里是建议内容。
:::

折叠框

折叠框适合收纳长配置、命令输出、步骤说明或旧文章里较长的代码块。

折叠框内部仍然可以写 Markdown：

列表
链接
代码块

npm run build

{{< collapse title="点击展开" open="true" >}}

这里是折叠内容。

{{< /collapse >}}

details 是同等别名：

{{< details title="更多信息" >}}
内容。
{{< /details >}}

选项卡

选项卡适合对比多个方案、语言版本、安装步骤或配置方式。

一个 tabs 里面放多个 tab。

tabs 可用 tabs="标题1,标题2" 设置导航标题，default="2" 设置默认打开项。

每个 tab 不要太短，否则普通小标题可能更清楚。

{{< tabs tabs="方案一,方案二" default="1" >}}

{{< tab index="1" title="方案一" >}}
第一段内容。
{{< /tab >}}

{{< tab index="2" title="方案二" >}}
第二段内容。
{{< /tab >}}

{{< /tabs >}}

卡片和引用

card / box 适合放一段独立信息，quote 适合引用。

卡片内部可以写普通 Markdown。它比提示块更中性，适合放材料清单、配置摘要或步骤结果。

短代码的目标不是取代 Markdown，而是在关键位置补一个更顺手的表达工具。

{{< card title="卡片标题" type="info" >}}
卡片内容。
{{< /card >}}

{{< quote author="作者" >}}
引用内容。
{{< /quote >}}

时间线

时间线适合记录版本、步骤、事件或迁移过程。

{{< timeline-item date="2026-06-15" title="补齐短代码能力" type="success" >}}

加入相册、下载、网盘、GitHub、豆瓣、iframe 等常用正文组件。

如果旧文里出现新的短代码，再把它映射到合适的静态组件。

{{< timeline >}}

{{< timeline-item date="2026-06-15" title="完成" type="success" >}}
事件内容。
{{< /timeline-item >}}

{{< /timeline >}}

按钮、徽章和彩色文字

{{< button href="/posts/" text="查看文章" color="primary" >}} {{< button href="/archive/" text="归档" color="info" outline="true" >}} {{< badge text="Shortcode" color="primary" >}}

这一行里有 {{< color "accent" >}}主题色文字{{< /color >}} 和 {{< color "red" >}}红色文字{{< /color >}}。

{{< button href="/posts/" text="查看文章" color="primary" >}}
{{< button href="/archive/" text="归档" color="info" outline="true" >}}
{{< badge text="Shortcode" color="primary" >}}
这一行里有 {{< color "accent" >}}主题色文字{{< /color >}}。

常用参数：

参数	说明
`href` / `url`	链接地址
`text` / `label` / `title`	按钮文字
`color` / `type`	`primary`、`info`、`success`、`warning`、`danger`、`dark`、`light`
`size`	`small`、`normal`、`large`
`outline`	`true` 时显示描边按钮
`block`	`true` 时占满整行

链接卡片

链接卡片适合替代裸链接，下载卡片和网盘卡片适合放资源入口。

{{< linkcard url="https://astro.build/" title="Astro" desc="用于构建内容驱动网站的前端框架。" site="Astro" image="/og.svg" >}}

{{< netdisk url="https://example.com" title="网盘资源示例" code="abcd" >}}

{{< douban type="book" id="1234567" title="豆瓣条目示例" rating="8.8" cover="/img/default-cover.webp" >}}

{{< linkcard url="https://astro.build/" title="Astro" desc="内容驱动网站框架" site="Astro" image="/og.svg" >}}
{{< github repo="withastro/astro" desc="Astro 官方仓库" >}}
{{< download url="/files/theme.zip" title="主题包下载" desc="ZIP / 12 MB" >}}
{{< netdisk url="https://pan.example.com/s/xxx" title="网盘资源" code="abcd" >}}
{{< douban type="book" id="1234567" title="书名" rating="8.8" cover="/img/default-cover.webp" >}}

图片和相册

普通图片优先使用 Markdown：

![图片说明](/img/default-cover.webp)

短代码图片适合加标题或做 Live Photo。

{{< gallery images="/og.svg,/img/default-cover.webp,/img/avatar.png" captions="OG 图|默认封面|头像" title="相册组示例" >}}

{{< image src="/img/default-cover.webp" alt="说明" caption="图片标题" >}}
{{< picture src="/img/default-cover.webp" title="图片标题" >}}
{{< livephoto src="/img/photo.webp" video="/video/live.mp4" caption="动态照片" >}}
{{< gallery images="/img/a.webp,/img/b.webp,/img/c.webp" captions="第一张|第二张|第三张" title="相册标题" >}}

视频和网页嵌入

本地视频、B 站、YouTube、抖音外链和网页 iframe 都可以写。

{{< bilibili bvid="BVxxxx" >}}
{{< youtube id="dQw4w9WgXcQ" >}}
{{< video src="/video/demo.mp4" poster="/img/default-cover.webp" controls="true" >}}
{{< video "https://www.bilibili.com/video/BVxxxx" >}}
{{< douyin url="https://www.douyin.com/video/xxx" title="抖音视频" >}}
{{< iframe src="https://example.com" title="嵌入网页" height="520" >}}
{{< embed url="https://example.com" title="嵌入内容" ratio="4/3" >}}

第三方视频和网页嵌入可能受对方防盗链、跨域、隐私策略影响；如果加载失败，优先改成 linkcard。

音乐和音频

本地音频用 audio，第三方音乐用 music / netease。

{{< audio src="/audio/demo.mp3" title="Demo Track" artist="Demius" cover="/img/default-cover.webp" >}}

{{< audio src="/audio/demo.mp3" title="Demo Track" artist="Demius" cover="/img/default-cover.webp" >}}

{{< music server="netease" type="song" id="27583305" >}}
{{< music server="netease" type="playlist" id="4977885420" >}}
{{< netease id="27583305" >}}
{{< music auto="https://music.163.com/#/song?id=27583305" >}}

music 会自动加载 APlayer / MetingJS。第三方音乐能否播放取决于音乐平台接口和版权状态。

隐藏内容和评论可见

静态站点没有服务端权限判断，所以 encrypt、secret、reply-visible 会降级为折叠块展示，用来兼容旧文章布局。

这里是旧站评论可见内容在静态站里的展示方式。

{{< encrypt hint="提示文字" >}}
隐藏内容。
{{< /encrypt >}}

{{< reply-visible notice="评论后查看" button="查看内容" >}}
旧站评论可见内容。
{{< /reply-visible >}}

常见问题

短代码没有生效

先检查是否写成独立一行。块级短代码推荐前后都空一行：

{{< collapse title="标题" >}}

内容。

{{< /collapse >}}

参数里有空格怎么办

用英文引号包起来：

{{< button href="/posts/" text="查看全部文章" >}}

旧文章里的短代码要怎么迁移

优先保留原写法。半神已经兼容常见的 Handsome / Hugo 风格短代码；如果某个旧短代码仍然显示为原始文本，再到 src/utils/remarkDemiusShortcodes.mjs 里补映射和渲染函数。