New docs for customizable previews

Mudd-d · pull · Apr 10, 2022 · Apr 11, 2022 · Apr 13, 2022 · Apr 13, 2022
commit 5f92e9651a51739cff1a4422802efe3485cf609f
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -15,6 +15,7 @@
   - [Wiki Links](editor/wiki-links.md)
   - [Math Formulas](editor/math.md)
   - [Diagrams](editor/diagrams.md)
+  - [Custom Preview](editor/custom-preview.md)
   - [Image Uploading](editor/image-uploading.md)
   - [Keyboard Shortcuts](editor/cheatsheet.md)
 - Text Actions

diff --git a/docs/cn/_sidebar.md b/docs/cn/_sidebar.md
@@ -14,6 +14,7 @@
   - [Wiki 链接](cn/editor/wiki-links.md)
   - [数学公式](cn/editor/math.md)
   - [绘制图表](cn/editor/diagrams.md)
+  - [自定义预览](cn/editor/custom-preview.md)
   - [图片上传](cn/editor/image-uploading.md)
   - [键盘快捷键](cn/editor/cheatsheet.md)
 - 文本动作

diff --git a/docs/cn/editor/custom-preview.md b/docs/cn/editor/custom-preview.md
@@ -0,0 +1,50 @@
+# 自定义预览
+
+Taio 可以使用 `CSS` 和 `JavaScript` 来定制预览的样式和行为。
+
+要了解更多关于 CSS 和 JavaScript 的信息，请参考：
+
+- [Mozilla 的 CSS 指南](https://developer.mozilla.org/en-US/docs/Web/CSS)
+- [Mozilla 的 JavaScript 指南](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+
+## 自定义样式
+
+样式表可以在预览设置、自定义样式找到。Taio 内置了几个样式表的例子，您也可以创建自己的。
+
+这些文件是纯文本文件，位于 `/Taio/Templates/PreviewStyles`，使用您喜欢的源代码编辑器在那里添加文件也可以。
+
+> Taio 自动管理文件同步，它在可能的时候使用 iCloud 同步。
+
+### 根元素
+
+生成的 HTML 使用 `<article class="markdown-body"><article/>` 作为它的根元素，想要控制这个元素的样式，可以考虑使用像这样的 css 选择器：
+
+```css
+.markdown-body h1 {
+
+}
+```
+
+这将改变生成的文章中顶级标题的样式。
+
+一般来说，我们需要考虑大量的选择器来进行完整的覆盖，如 `h1`、`h2`、`h3`、`hr`、`blockquote`、`table` 等。了解需要覆盖的内容最简单方法是检查生成的 HTML 文件。
+
+### 正文背景颜色
+
+如果可能的话，尽量避免在 HTML body 上使用半透明的背景色。
+
+当为带有半透明背景的 HTML 生成 PDF 时，Taio 会重新混合颜色以去除 alpha 通道，以便用相同的颜色填充 PDF 纸张的背景。
+
+### 快速切换器
+
+要在预览模式下快速切换样式表，长按预览按钮（在 macOS 上右键），我们将看到一个弹出菜单。
+
+## 自定义行为
+
+添加自定义行为的 JavaScript 文件可以通过预览设置、自定义脚本找到。默认的实现只是一个占位符，您可以根据需要来改变它。
+
+这个文件是一个纯文本文件，位于 `/Taio/Templates/PreviewPlugins.js`，使用您喜欢的源代码编辑器编辑它也可以。
+
+通过这个 JavaScript 文件，您可以为预览添加更多的扩展。
+
+> Taio 自动管理文件同步，它在可能的时候使用 iCloud 同步。
diff --git a/docs/cn/whatsnew.md b/docs/cn/whatsnew.md
@@ -1,3 +1,7 @@
+### 🪄 自定义预览
+
+我们现在可以通过 CSS 和 JavaScript 自定义预览的样式和行为，[了解更多](https://docs.taio.app/#/cn/editor/custom-preview)。
+
 ### 🔥 全面适配 iOS 16
 
 Taio 已经为 iOS 16 的更新做好全面适配，带来了包括但不限于如下主要更新：
@@ -25,14 +29,4 @@ Taio 已经为 iOS 16 的更新做好全面适配，带来了包括但不限于
 
 ### 🖋 改进文件创建
 
-增加了对 `文件模板` 和可定制的 `默认文件名` 的支持。现在您可以使用强大的文本动作来创建文件，[了解更多](https://docs.taio.app/#/cn/editor/file-creation)。
-
-### 🔥 重磅更新
-
-- 针对 iOS 16 的界面优化
-- 全新的小组件
-- 支持 PlantUML
-- 针对文件设置高亮模式
-- 备份和恢复动作库
-- 更好的文件导入
-- 大量的修复和重新设计
+增加了对 `文件模板` 和可定制的 `默认文件名` 的支持。现在您可以使用强大的文本动作来创建文件，[了解更多](https://docs.taio.app/#/cn/editor/file-creation)。
diff --git a/docs/editor/custom-preview.md b/docs/editor/custom-preview.md
@@ -0,0 +1,50 @@
+# Custom Preview
+
+It's possible to customize preview styles and behaviors using `CSS` and `JavaScript`.
+
+To learn more about CSS and JavaScript, please refer to:
+
+- [Mozilla's CSS Guide](https://developer.mozilla.org/en-US/docs/Web/CSS)
+- [Mozilla's JavaScript Guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+
+## Customize Styles
+
+Style sheets can be found by going preview settings, custom styles. There're several built-in example style sheets, you can also create your own.
+
+These files are just plain text files located in `/Taio/Templates/PreviewStyles`, adding files there using your favorite source code editor works too.
+
+> Taio automatically manages file sync, it uses iCloud when possible.
+
+### Root Element
+
+The generated HTML uses `<article class="markdown-body"><article/>` as its root element, to control styles inside this element, consider using css selectors like this:
+
+```css
+.markdown-body h1 {
+
+}
+```
+
+This changes the style of top-level headings in the generated article.
+
+Generally, we will need to cover bunches of selectors to have a complete overwritten, such as `h1`, `h2`, `h3`, `hr`, `blockquote`, `table`, etc. The easiest way to learn what needs to be covered is inspecting a generated HTML file.
+
+### Body Background Color
+
+If possible, try to avoid using translucent background colors on the HTML body.
+
+When generating PDF for HTML with translucent background color, Taio remixes the color to remove the alpha channel, in order to fill the PDF paper background with the same color.
+
+### Quick Switcher
+
+To quickly switch between style sheets in preview mode, long press the preview button (right-click on macOS) and we will see a popup menu.
+
+## Customize Behaviors
+
+The JavaScript file that adds custom behaviors can be found by going preview settings, custom plugins. The default implementation is just a placeholder, and you can change it to match your needs.
+
+This file is just a plain text file located in `/Taio/Templates/PreviewPlugins.js`, editing it using your favorite source code editor works too.
+
+With this JavaScript file, you can add more extensions to the preview.
+
+> Taio automatically manages file sync, it uses iCloud when possible.
diff --git a/docs/whatsnew.md b/docs/whatsnew.md
@@ -1,3 +1,7 @@
+### 🪄 Customizable Previews
+
+We can now customize preview styles and behaviors with CSS and JavaScript, [learn more](https://docs.taio.app/#/editor/custom-preview).
+
 ### 🔥 Refreshed for iOS 16
 
 Taio has been refreshed for the iOS 16 update, with major updates including but not limited to:
@@ -25,14 +29,4 @@ Text actions can embed other text actions, which means they are reusable now.
 
 ### 🖋 Improve File Creation
 
-Added support for both `file templates` and customizable `default file name`. You can now create files using powerful text actions, [learn more](https://docs.taio.app/#/editor/file-creation).
-
-### 🔥 Major Update
-
-- iOS 16 UX refresh
-- New widgets
-- PlantUML
-- Per-file highlight mode
-- Actions backup & restore
-- Better import
-- Lots of fixes and redesigns
+Added support for both `file templates` and customizable `default file name`. You can now create files using powerful text actions, [learn more](https://docs.taio.app/#/editor/file-creation).