touying-author

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Touying Author

Touying 创作指南

Guide Typst presentation authoring with Touying, emphasizing clean structure, repeatable configuration, and slide-safe patterns.

指导使用Touying进行Typst演示文稿创作，强调清晰的结构、可复用的配置以及幻灯片安全的编写模式。

Quick start

快速入门

Import Touying and a theme, then apply the theme with
```
#show: <theme>.with(...)
```
.
Keep configuration centralized; include slide content from separate files.
Use headings to create slides; use
```
#slide
```
for custom layouts or animations.
Start from
```
examples/simple.typ
```
for a minimal deck, or
```
examples/default.typ
```
for the bare theme.

Snippet from

examples/simple.typ

typst

#import "@preview/touying:0.6.1": *
#import themes.simple: *

#show: simple-theme.with(
  aspect-ratio: "16-9",
  footer: [Simple slides],
)

导入Touying和一个主题，然后使用
```
#show: <theme>.with(...)
```
应用该主题。
集中管理配置；从单独的文件中引入幻灯片内容。
使用标题创建幻灯片；使用
```
#slide
```
实现自定义布局或动画。
可以从
```
examples/simple.typ
```
开始搭建极简演示文稿，或从
```
examples/default.typ
```
开始使用基础主题。

来自

examples/simple.typ

的代码片段：

typst

#import "@preview/touying:0.6.1": *
#import themes.simple: *

#show: simple-theme.with(
  aspect-ratio: "16-9",
  footer: [Simple slides],
)

Best practices and code structure

最佳实践与代码结构

Use a single entry file (e.g.,
```
main.typ
```
) that applies
```
#show
```
and all
```
config-*
```
calls.
For multi-file decks, follow the
```
globals.typ
```
+
```
main.typ
```
+
```
content.typ
```
pattern; use
```
#include
```
for content and
```
#import
```
for globals to avoid circular refs.
Docs use both
```
config.typ
```
(see
```
docs/start.md
```
) and
```
globals.typ
```
(see
```
docs/multi-file.md
```
) for the shared config file; pick one name and use it consistently in your project.

For large decks, move

content.typ

into

sections/

and include

sections/content.typ

(and optional

sections/another-section.typ

) from

main.typ

Prefer

config-page

config-common

config-info

config-colors

config-methods

, and

config-store

over direct

set page

or ad-hoc global

show

Use headings for most slides; use
```
config-common(slide-level: n)
```
to choose which heading levels create slides.
Use
```
#slide
```
only for custom layout or animation; always wrap slide functions with
```
touying-slide-wrapper
```
.

For callback-style animation (

#slide(repeat: n, self => [...])

), set

repeat

explicitly and use

utils.methods(self)

to access

uncover

only

, and

alternatives

使用单个入口文件（例如
```
main.typ
```
）来应用
```
#show
```
和所有
```
config-*
```
调用。
对于多文件演示文稿，遵循
```
globals.typ
```
+
```
main.typ
```
+
```
content.typ
```
的模式；使用
```
#include
```
引入内容，使用
```
#import
```
引入全局文件以避免循环引用。
文档中同时使用
```
config.typ
```
（参见
```
docs/start.md
```
）和
```
globals.typ
```
（参见
```
docs/multi-file.md
```
）作为共享配置文件；在项目中选择一个名称并保持一致。
对于大型演示文稿，将
```
content.typ
```
移入
```
sections/
```
目录，并从
```
main.typ
```
中引入
```
sections/content.typ
```
（以及可选的
```
sections/another-section.typ
```
）。

优先使用

config-page

、

config-common

、

config-info

、

config-colors

、

config-methods

和

config-store

，而非直接使用

set page

或临时的全局

show

设置。

大多数幻灯片使用标题创建；使用
```
config-common(slide-level: n)
```
来指定哪些标题级别可创建幻灯片。
仅在需要自定义布局或动画时使用
```
#slide
```
；始终用
```
touying-slide-wrapper
```
包裹幻灯片函数。

对于回调式动画（

#slide(repeat: n, self => [...])

），显式设置

repeat

参数，并使用

utils.methods(self)

来访问

uncover

、

only

和

alternatives

。

Single-file structure

单文件结构

.
├── globals.typ
├── main.typ
└── content.typ

.
├── globals.typ
├── main.typ
└── content.typ

Multi-file structure

多文件结构

.
├── globals.typ
├── main.typ
└── sections/
    ├── content.typ
    └── another-section.typ

.
├── globals.typ
├── main.typ
└── sections/
    ├── content.typ
    └── another-section.typ

Core API map (exports)

核心API映射（导出项）

Slides:

touying-slides

slide

touying-slide

touying-slide-wrapper

empty-slide

Dynamics:

pause

meanwhile

uncover

only

effect

alternatives

alternatives-match

alternatives-fn

alternatives-cases

Config:

config-common

config-page

config-info

config-colors

config-methods

config-store

default-config

touying-set-config

appendix

Utilities:
```
utils.*
```
(fit-to-height, fit-to-width, cover helpers, progress, heading helpers)

Components:

components.side-by-side

components.adaptive-columns

components.progressive-outline

components.custom-progressive-outline

Integrations:

touying-reducer

touying-equation

touying-mitex

speaker-note

pdfpc.*

Recall:
```
touying-recall
```
,
```
touying-fn-wrapper
```

幻灯片：

touying-slides

、

slide

、

touying-slide

、

touying-slide-wrapper

、

empty-slide

动态效果：

pause

、

meanwhile

、

uncover

、

only

、

effect

、

alternatives

、

alternatives-match

、

alternatives-fn

、

alternatives-cases

配置：

config-common

、

config-page

、

config-info

、

config-colors

、

config-methods

、

config-store

、

default-config

、

touying-set-config

、

appendix

工具函数：
```
utils.*
```
（高度适配、宽度适配、封面辅助函数、进度、标题辅助函数）

组件：

components.side-by-side

、

components.adaptive-columns

、

components.progressive-outline

、

components.custom-progressive-outline

集成：

touying-reducer

、

touying-equation

、

touying-mitex

、

speaker-note

、

pdfpc.*

回调：
```
touying-recall
```
、
```
touying-fn-wrapper
```

Slide structure and headings

幻灯片结构与标题

Use heading labels to control numbering/outline/bookmarks: use

<touying:hidden>

(see

docs/code-styles.md

), and see

docs/changelog.md

for

<touying:unnumbered>

<touying:unoutlined>

<touying:unbookmarked>

, and

<touying:skip>

Use

components.adaptive-columns(outline(...))

for a table of contents slide; use

components.progressive-outline

for progress-aware outlines.

Use
```
== <touying:hidden>
```
to insert a blank title slide and clear the previous heading context.
Use
```
#pagebreak()
```
or
```
---
```
to split slides without changing headings.
Use
```
#empty-slide[...]
```
for slides without header/footer.
Use
```
config-common(handout: true)
```
to keep only the last subslide per slide in handout output.
Use
```
#show: appendix
```
to freeze last-slide counts after the main deck.

Snippet from

examples/default.typ

typst

= Outline <touying:hidden>

#components.adaptive-columns(outline(title: none, indent: 1em))

使用标题标签控制编号/大纲/书签：使用

<touying:hidden>

（参见

docs/code-styles.md

），并查看

docs/changelog.md

了解

<touying:unnumbered>

、

<touying:unoutlined>

、

<touying:unbookmarked>

和

<touying:skip>

的用法。

使用
```
components.adaptive-columns(outline(...))
```
创建目录幻灯片；使用
```
components.progressive-outline
```
创建支持进度显示的大纲。
使用
```
== <touying:hidden>
```
插入空白标题幻灯片并清除之前的标题上下文。
使用
```
#pagebreak()
```
或
```
---
```
在不改变标题的情况下拆分幻灯片。
使用
```
#empty-slide[...]
```
创建没有页眉/页脚的幻灯片。
使用
```
config-common(handout: true)
```
在讲义输出中仅保留每个幻灯片的最后一个子幻灯片。
使用
```
#show: appendix
```
在主演示文稿结束后冻结最后幻灯片的计数。

来自

examples/default.typ

的代码片段：

typst

= Outline <touying:hidden>

#components.adaptive-columns(outline(title: none, indent: 1em))

Animations and dynamic content

动画与动态内容

Use
```
#pause
```
and
```
#meanwhile
```
for simple reveals; avoid using them inside
```
context
```
where marks are not supported.
Use
```
#uncover
```
to reserve layout space; use
```
#only
```
to remove layout space when hidden.
When marks cause warnings, use callback-style slides with
```
repeat
```
and
```
utils.methods(self)
```
.
For math animations, use
```
pause
```
/
```
meanwhile
```
inside
```
$ ... $
```
; use
```
touying-equation
```
when you need the helper for inline equation text (you can also use
```
#pause
```
or
```
#pause;
```
).
See
```
examples/example.typ
```
for simple/complex/callback animations and equation animations.

Snippet from

examples/simple.typ

typst

== Dynamic slide

Did you know that...

#pause

...you can see the current section at the top of the slide?

Snippet from

examples/example.typ

typst

#slide(
  repeat: 3,
  self => [
    #let (uncover, only, alternatives) = utils.methods(self)

    At subslide #self.subslide, we can

    use #uncover("2-")[`#uncover` function] for reserving space,

    use #only("2-")[`#only` function] for not reserving space,

    #alternatives[call `#only` multiple times \u{2717}][use `#alternatives` function #sym.checkmark] for choosing one of the alternatives.
  ],
)

使用
```
#pause
```
和
```
#meanwhile
```
实现简单的内容展示；避免在不支持标记的
```
context
```
内部使用它们。
使用
```
#uncover
```
预留布局空间；使用
```
#only
```
在内容隐藏时移除布局空间。
当标记导致警告时，使用带
```
repeat
```
参数的回调式幻灯片和
```
utils.methods(self)
```
。
对于数学公式动画，在
```
$ ... $
```
内部使用
```
pause
```
/
```
meanwhile
```
；当需要内联公式文本的辅助函数时，使用
```
touying-equation
```
（也可以使用
```
#pause
```
或
```
#pause;
```
）。
查看
```
examples/example.typ
```
了解简单/复杂/回调式动画以及公式动画的示例。

来自

examples/simple.typ

的代码片段：

typst

== Dynamic slide

Did you know that...

#pause

...you can see the current section at the top of the slide?

来自

examples/example.typ

的代码片段：

typst

#slide(
  repeat: 3,
  self => [
    #let (uncover, only, alternatives) = utils.methods(self)

    At subslide #self.subslide, we can

    use #uncover("2-")[`#uncover` function] for reserving space,

    use #only("2-")[`#only` function] for not reserving space,

    #alternatives[call `#only` multiple times \u{2717}][use `#alternatives` function #sym.checkmark] for choosing one of the alternatives.
  ],
)

Layout and theming

布局与主题

Use
```
composer
```
in
```
#slide
```
for columns; pass
```
(1fr, 2fr)
```
or a custom
```
grid
```
function.
Use
```
config-page
```
for margin, header, footer, and background; do not use
```
set page
```
directly.

Use

config-methods(cover: utils.semi-transparent-cover.with(alpha: 85%))

only when layout changes are acceptable.

Use
```
config-store
```
to stash theme-specific values for headers/footers or navigation elements.
Use
```
config-common(new-section-slide-fn: none)
```
to disable automatic section slides, or provide a custom function to replace them.
Apply global styles either around
```
#show: <theme>.with(...)
```
or via
```
config-methods(init: ...)
```
in a theme.
Use
```
config-info(...)
```
for title/author/date and
```
config-common(datetime-format: ...)
```
to control date formatting.

Snippet from

examples/default.typ

typst

#import "@preview/touying:0.6.1": *
#import themes.default: *

#import "@preview/numbly:0.1.0": numbly

#show: default-theme.with(
  aspect-ratio: "16-9",
  config-common(
    slide-level: 3,
    zero-margin-header: false,
  ),
  config-colors(primary: blue),
  config-methods(alert: utils.alert-with-primary-color),
  config-page(
    header: text(gray, utils.display-current-short-heading(level: 2)),
  ),
)

在
```
#slide
```
中使用
```
composer
```
创建分栏；传入
```
(1fr, 2fr)
```
或自定义的
```
grid
```
函数。
使用
```
config-page
```
设置边距、页眉、页脚和背景；不要直接使用
```
set page
```
。

仅在可接受布局变化时，使用

config-methods(cover: utils.semi-transparent-cover.with(alpha: 85%))

。

使用
```
config-store
```
存储主题特定的值，用于页眉/页脚或导航元素。
使用
```
config-common(new-section-slide-fn: none)
```
禁用自动生成的章节幻灯片，或提供自定义函数替换它们。
全局样式可以在
```
#show: <theme>.with(...)
```
周围设置，或通过主题中的
```
config-methods(init: ...)
```
应用。
使用
```
config-info(...)
```
设置标题/作者/日期，并使用
```
config-common(datetime-format: ...)
```
控制日期格式。

来自

examples/default.typ

的代码片段：

typst

#import "@preview/touying:0.6.1": *
#import themes.default: *

#import "@preview/numbly:0.1.0": numbly

#show: default-theme.with(
  aspect-ratio: "16-9",
  config-common(
    slide-level: 3,
    zero-margin-header: false,
  ),
  config-colors(primary: blue),
  config-methods(alert: utils.alert-with-primary-color),
  config-page(
    header: text(gray, utils.display-current-short-heading(level: 2)),
  ),
)

Speaker notes and presenter tools

演讲者备注与演示工具

Add notes with
```
#speaker-note[...]
```
.

Show notes on second screen with

config-common(show-notes-on-second-screen: right)

bottom

Export pdfpc metadata with

enable-pdfpc: true

and

typst query --field value --one "<pdfpc-file>"

使用
```
#speaker-note[...]
```
添加备注。

使用

config-common(show-notes-on-second-screen: right)

或

bottom

在第二个屏幕上显示备注。

启用

enable-pdfpc: true

并使用

typst query --field value --one "<pdfpc-file>"

导出pdfpc元数据。

Use bundled docs and examples

使用内置文档与示例

Read only the specific docs needed for the task; avoid loading the full docs tree.
Read
```
docs/start.md
```
and
```
docs/intro.md
```
for basics and import patterns.
Read
```
docs/multi-file.md
```
for multi-file layout and include patterns.
Read
```
docs/layout.md
```
and
```
docs/sections.md
```
for slide-level and heading behavior.
Read
```
docs/code-styles.md
```
for simple vs block style and pagination tricks.
Read
```
docs/global-settings.md
```
for global styles and
```
config-info
```
usage.
Read
```
docs/dynamic/*.md
```
for
```
pause
```
,
```
meanwhile
```
, cover behavior, and equation animation.
Read
```
docs/themes/*.md
```
for theme-specific APIs and defaults.
Read
```
docs/external/*.md
```
for pdfpc and Pympress usage.
Read
```
docs/integration/*.md
```
for CeTZ/Fletcher/Theorion/MiTeX integrations.
Use
```
examples/*.typ
```
as working templates for each theme.

仅阅读完成任务所需的特定文档；避免加载完整的文档树。
阅读
```
docs/start.md
```
和
```
docs/intro.md
```
了解基础用法和导入模式。
阅读
```
docs/multi-file.md
```
了解多文件布局和引入模式。
阅读
```
docs/layout.md
```
和
```
docs/sections.md
```
了解幻灯片级别和标题行为。
阅读
```
docs/code-styles.md
```
了解简洁式与块式写法以及分页技巧。
阅读
```
docs/global-settings.md
```
了解全局样式和
```
config-info
```
的用法。
阅读
```
docs/dynamic/*.md
```
了解
```
pause
```
、
```
meanwhile
```
、封面行为和公式动画。
阅读
```
docs/themes/*.md
```
了解主题特定的API和默认设置。
阅读
```
docs/external/*.md
```
了解pdfpc和Pympress的用法。
阅读
```
docs/integration/*.md
```
了解CeTZ/Fletcher/Theorion/MiTeX的集成。
使用
```
examples/*.typ
```
作为每个主题的可用模板。

File tree (docs and examples)

文件树（文档与示例）

docs/
├── build-your-own-theme.md
├── changelog.md
├── code-styles.md
├── dynamic
│   ├── complex.md
│   ├── cover.md
│   ├── equation.md
│   ├── handout.md
│   ├── other.md
│   └── simple.md
├── external
│   ├── pdfpc.md
│   ├── pympress.md
│   └── typst-preview.md
├── global-settings.md
├── integration
│   ├── cetz.md
│   ├── codly.md
│   ├── fletcher.md
│   ├── mitex.md
│   ├── pinit.md
│   └── theorion.md
├── intro.md
├── layout.md
├── multi-file.md
├── progress
│   ├── counters.md
│   └── sections.md
├── sections.md
├── start.md
├── themes
│   ├── aqua.md
│   ├── custom.md
│   ├── dewdrop.md
│   ├── metropolis.md
│   ├── simple.md
│   ├── stargazer.md
│   └── university.md
└── utilities
    └── fit-to.md

examples/
├── aqua-zh.typ
├── aqua.typ
├── default.typ
├── dewdrop.typ
├── example.typ
├── metropolis.typ
├── simple.typ
├── stargazer.typ
└── university.typ

docs/
├── build-your-own-theme.md
├── changelog.md
├── code-styles.md
├── dynamic
│   ├── complex.md
│   ├── cover.md
│   ├── equation.md
│   ├── handout.md
│   ├── other.md
│   └── simple.md
├── external
│   ├── pdfpc.md
│   ├── pympress.md
│   └── typst-preview.md
├── global-settings.md
├── integration
│   ├── cetz.md
│   ├── codly.md
│   ├── fletcher.md
│   ├── mitex.md
│   ├── pinit.md
│   └── theorion.md
├── intro.md
├── layout.md
├── multi-file.md
├── progress
│   ├── counters.md
│   └── sections.md
├── sections.md
├── start.md
├── themes
│   ├── aqua.md
│   ├── custom.md
│   ├── dewdrop.md
│   ├── metropolis.md
│   ├── simple.md
│   ├── stargazer.md
│   └── university.md
└── utilities
    └── fit-to.md

examples/
├── aqua-zh.typ
├── aqua.typ
├── default.typ
├── dewdrop.typ
├── example.typ
├── metropolis.typ
├── simple.typ
├── stargazer.typ
└── university.typ