tldraw 文档写作风格指南从 SDK 参考文档到技术博客的完整规范【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw本文档是 tldraw SDK 官方文档写作规范的核心指南定义了 apps/docs/content/ 目录下所有 SDK 文档的规则与约定。它规定了文档结构、开场模式、代码示例、交叉引用方式、渐进式披露原则以及面向工程师的「Nugget」技术博客写作风格。读完本文你将掌握一套可直接复用的文档工程方法论如何写一个清晰的开场定义、如何用「概念—解释—代码」组织章节、如何在参考文档与工程博客之间切换语气以及如何用检查清单自审成稿。本指南的前置条件是先阅读 VOICE.md语气与风格指南本文档在其基础上补充了文档场景特有的模式。两个文件配合使用VOICE 解决「听起来像不像 tldraw」的问题本指南解决「结构上对不对」的问题。文档结构开场模式一句概念一个句子每篇文档的第一句话应该给出清晰、直接的定义而不是铺垫The Editor class is the main way of controlling tldraws editor.In tldraw, a shape is something that can exist on the page, like an arrow, an image, or some text.In tldraw, persistence means storing information about the editors state to a database and then restoring it later.一个句子只讲一个概念。如果开场把定义、使用场景和 API 引用打包在一起就要拆开不要The scribble system draws temporary freehand paths for pointer-based interactions, used for visual feedback during erasing, laser drawing, or scribble-brush selection, accessed through Editor#scribbles.要The scribble system draws temporary freehand paths for pointer-based interactions. Use scribbles to show visual feedback during tool operations like erasing, laser pointer drawing, or scribble-brush selection.API 引用可以放在开场段落之后或在首次相关处内联出现。这条规则在仓库中已有实例参考 editor.mdx 的开场——「The Editor class is the main way of controlling tldraws editor. You can use it to manage the editors internal state, make changes to the document, or respond to changes that have occurred.」直接定义后立刻给出使用方向随后才展开 Editor#createShapes 等方法引用。概念、解释、代码每个概念后面都要跟一个可运行的示例。这是 tldraw 文档的第一原则You can access the editor in two ways:From the Tldraw componentsonMountcallback:function App() { return ( Tldraw onMount{(editor) { // your editor code here }} / ) }对照 editor.mdx 可以看到这个模式的完整落地先写「You can access the editor in two ways」再用编号列表给出onMount回调与useEditor钩子两种方式每种都配完整 TSX 代码。useEditor的例子还进一步演示了「组件必须渲染在 Tldraw 内部」这一限制function InsideOfContext() { const editor useEditor() // your editor code here return null } function App() { return ( Tldraw InsideOfContext / /Tldraw ) }渐进式披露从简单到复杂推进先写最常见的用例逐步增加复杂度把边界情况和高级模式留给后面的章节来自 persistence 文档的实例见 persistence.mdx先讲persistenceKeyprop最简单再讲 State snapshots更多控制然后讲storeprop完全控制最后讲 Migrations高级persistence.mdx 的实际组织完全遵循这一层级Local persistence → Snapshots → The store → Multiplayer sync → Migrations → Examples每一节都配完整的可复制代码。例如persistenceKey一节给出最小可用应用import { Tldraw } from tldraw import tldraw/tldraw.css export default function App() { return ( div style{{ position: fixed, inset: 0 }} Tldraw persistenceKeymy-document / /div ) }而store一节则展示如何用createTLStore与loadSnapshot自建存储import { useState } from react import { createTLStore, loadSnapshot, Tldraw } from tldraw export default function App() { const [store] useState(() { const store createTLStore() const saved localStorage.getItem(my-drawing) if (saved) { loadSnapshot(store, JSON.parse(saved)) } return store }) return Tldraw store{store} / }短段落段落保持 1-3 句。密集的文字块难以扫读要Meta information is information that is not used by tldraw but is instead used by your application. For example, you might want to store the name of the user who created a shape, or the date that the shape was created.不要Meta information is additional data that can be attached to shapes and is not used internally by tldraw but can be leveraged by your application for custom functionality. This could include things like the user who created the shape, timestamps, custom identifiers, or any other application-specific data that you want to associate with shapes but dont want to store in the props object.用表格组织相关信息用表格组织相关的方法、选项或概念MethodDescriptionEditor#setCameraMoves the camera to the provided coordinates.Editor#zoomInZooms the camera in to the nearest zoom step.Editor#zoomOutZooms the camera out to the nearest zoom step.editor.mdx 提供了一个大规模表格的实例把编辑器的全部能力按 Data、Interaction、View、State、Configuration、Output 六个区域组织成表每行指向对应的 SDK 功能文档Signals、Store、Tools、History 等。当信息真正具有平行结构时表格比列表更利于扫描。笔记与提示用 blockquote 承载重要的补充说明If all youre interested in is the state belowroot, there is a convenience method,Editor#getCurrentToolId, that can help.警告类信息使用更强的 Callout 语法Callout typewarning You must make sure that the tldraw version in your client matches the version on the server. /Callout这条警告对应 tldraw 同步架构中的一个真实约束客户端与服务器版本必须匹配否则记录 schema 可能无法互相迁移。交叉引用放开链接与其把一切讲透不如在文中内联引用相关概念For more information about how to synchronize the store with other processes, see the Persistence page.persistence.mdx 每节末尾都遵循此模式例如 store 一节以「See Store for details on store operations, listening to changes, queries, and transactions.」收尾把深水区留给专门页面。API 引用使用统一格式链接到 API 文档时使用MethodName模式Use the Editor#createShapes method.See TLInstancePresence for the full record type.MethodName使用类名#方法名的格式让读者一眼知道该去哪里查。指向可运行示例只要存在可运行示例就优先链接示例而不是只给代码片段For an example of how to create custom shapes, see our custom shapes example.persistence.mdx 的 Examples 一节集中演示了这一做法用带描述的精简列表指向 Persistence key、Snapshots、Local storage、Store events、Shape with migrations 五个可直接运行的示例。Nuggets技术博客文章Nuggets 是短篇技术文章讲的是我们如何解决有趣的问题。它们与参考文档不同——更像公司工程博客上的文章。不同的开场模式参考文档以定义开场Nugget 以「框定问题」开场——用一两句话告诉读者这篇文章在讲什么、为什么有趣然后才进入正文。参考文档开场The Editor class is the main way of controlling tldraws editor.Nugget 开场The tldraw SDK is all about making the little details work. If youve ever used dashed lines in tldraw, you might have noticed that the dashes always line up with the corners of your shape, the handles of a spline, or the start and end of an arrow. While this might seem like the obvious way that dashesshouldwork, you might be surprised to learn that SVG offers no such feature. We implement these perfect dashes entirely ourselves.Heres how it works.Nugget 开场要建立三样东西context我们在谈什么、tension存在一个难题或未满足的预期、stakes你为什么要在乎。目的是把技术文章扎根在某种叙事语境里——这些问题并非凭空出现而是来自 canvas 领域内的细节、行为、约定或「什么才感觉对」的期望。真正的问题是如何写出代码、说服计算机去做让体验感觉正确的事。这种工作常常违反直觉因而有趣因为它揭示了交互本身或相关技术的某些本质。这个问题在仓库中确实有对应实现getPerfectDashProps.ts 中getPerfectDashProps通过计算dashCount Math.floor(totalLength / dashLength / (2 * ratio))并对snap取整、处理outset/skip端点、为超短路径回退为单 dash来生成两端完整、间距均匀的strokeDasharray与strokeDashoffset。这正是「SVG 原生做不到、我们自己算」的代码级证据。结构Nugget 通常遵循这条弧线框定问题——这是关于什么的我们遇到了什么问题并解决了它为什么它难、违反直觉或有趣展示洞见——让解决方案成立的关键想法是什么走一遍实现——代码与解释逐步增加复杂度收尾——这段代码在代码库中的位置、权衡、文件链接以及未探索的领域、还能做什么、相关问题语气差异Nugget 比参考文档更温暖。它允许用 the trick is... 或 the insight is... 来标记关键想法穿插简短旁白说明某事为什么难或有趣展示旅程而非只给终点「我们试过 X但 Y 更好用」以观点收尾「这个权衡是值得的」它仍然不该漫谈或过度解释使用空洞的重要性断言this is crucial for...过于随意或玩笑化描述我们做了什么而不是告诉读者做什么Nugget 解释 tldraw 是如何解决某个问题的——它们不是教程。要把方案表述为「我们这样做」而不是命令式指令。不要The solution: dont decide immediately. Watch what the fingers do, then commit once the pattern is clear.Instead of guessing, implement a state machine that starts undecided.要Since we dont have enough information to know either way, we defer the decision. The gesture handler watches what the pointers do, then commits once we know enough to recognize the interaction pattern.Instead of guessing, we use a state machine that starts undecided and resolves as more information comes in.读者从观察我们的做法中学习而不是被指挥该做什么。示例开场过于突兀读起来像文档Tldraw calculates dash patterns that fit paths exactly. Complete dashes at both ends, even spacing throughout.更好从我们的经验开始When we added dashed lines to tldraw, we wanted them to look right—complete dashes at both ends, even spacing, corners that line up on rectangles. SVGsstroke-dasharraydoesnt do this.也不错框定我们遇到的问题Arrow routing sounds simple until you try it. Given two shapes, draw a line between them that doesnt pass through anything else. We spent a while getting this right.关于 Nugget 的更完整规则长度 800-1500 词、好选题特征、评估清单参见 blog-guide.md。两者配合使用时注意定位差异docs-guide 的 Nugget 章节讲「如何在参考文档体系内写短文」blog-guide 则给出完整的博客写作方法论。优先级文档写作的优先级排序准确性——代码必须能跑API 引用必须正确清晰度——读一遍就能懂简洁性——说一次继续前进删掉那些重复别的章节已经展示过的内容可扫读性——短段落、清晰的标题、大量的代码准确性排在第一位不是偶然。文档中的代码会被读者直接复制运行API 引用会被当作权威依据。persistence.mdx 中每个代码块都是完整可运行的组件import { Tldraw } from tldraw起、export default function App()止而 editor.mdx 中editor.run的示例甚至注释了选项语义{ history: ignore } // Changes wont affect undo/redo正是「代码必须能跑」的体现。避免冗余章节如果详细示例已经演示了某个模式就不要在「Common use cases」一节里用更短的片段重复相同信息。要么只保留详细示例首选只保留快速参考片段确保每个章节都带来真正的新信息不要先给出完整的 eraser 实现然后又在「Common use cases Eraser」里放同一段代码的删减版。要完整实现只展示一次。如果需要快速参考章节就做成表格指向详细示例。这与上文「放开链接」的原则一脉相承重复是文档成本链接是文档杠杆。评估检查清单审查文档时逐项检查开场句——是否立刻定义了这是什么东西代码示例——每个概念后面是否都有可运行的代码渐进式披露——复杂度是否逐步上升链接——相关概念是否被交叉引用可扫读性——短段落、清晰的标题语气与风格部分对照 VOICE.md 的检查清单主动语态、自信断言、代词使用、句首大写、诚实说明限制、人类声音——无空洞重要性断言、无尾随分词、无套路化过渡。配套文件与进一步阅读本指南是 tldraw 文档体系中的一环完整的写作规范由以下文件共同构成docs-guide.md——本文档SDK 参考文档的结构规则VOICE.md——语气与风格基础含代词用法、主动语态、避免 AI 写作痕迹等通用规则blog-guide.md——技术博客Nugget的完整写作方法apps/docs/content/docs——规范的实际产出地editor.mdx、persistence.mdx 等页面是本文每条规则的活样板getPerfectDashProps.ts——Nugget 开场示例中「完美虚线」问题的真实实现把这套规范用于实践时可以先选一篇 apps/docs/content/docs 下的页面用评估检查清单逐条对照再尝试把某个界面细节比如虚线对齐、箭头避障写成 Nugget 风格的短文检验自己是否真的掌握了「框定问题」与「展示洞见」这两步。规则本身不是目的——让开发者能快速扫读、放心复制、一次跑通才是这套规范的终点。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 tldraw 文档写作风格指南：从 SDK 参考文档到技术博客的完整规范
tldraw 文档写作风格指南从 SDK 参考文档到技术博客的完整规范【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw本文档是 tldraw SDK 官方文档写作规范的核心指南定义了 apps/docs/content/ 目录下所有 SDK 文档的规则与约定。它规定了文档结构、开场模式、代码示例、交叉引用方式、渐进式披露原则以及面向工程师的「Nugget」技术博客写作风格。读完本文你将掌握一套可直接复用的文档工程方法论如何写一个清晰的开场定义、如何用「概念—解释—代码」组织章节、如何在参考文档与工程博客之间切换语气以及如何用检查清单自审成稿。本指南的前置条件是先阅读 VOICE.md语气与风格指南本文档在其基础上补充了文档场景特有的模式。两个文件配合使用VOICE 解决「听起来像不像 tldraw」的问题本指南解决「结构上对不对」的问题。文档结构开场模式一句概念一个句子每篇文档的第一句话应该给出清晰、直接的定义而不是铺垫The Editor class is the main way of controlling tldraws editor.In tldraw, a shape is something that can exist on the page, like an arrow, an image, or some text.In tldraw, persistence means storing information about the editors state to a database and then restoring it later.一个句子只讲一个概念。如果开场把定义、使用场景和 API 引用打包在一起就要拆开不要The scribble system draws temporary freehand paths for pointer-based interactions, used for visual feedback during erasing, laser drawing, or scribble-brush selection, accessed through Editor#scribbles.要The scribble system draws temporary freehand paths for pointer-based interactions. Use scribbles to show visual feedback during tool operations like erasing, laser pointer drawing, or scribble-brush selection.API 引用可以放在开场段落之后或在首次相关处内联出现。这条规则在仓库中已有实例参考 editor.mdx 的开场——「The Editor class is the main way of controlling tldraws editor. You can use it to manage the editors internal state, make changes to the document, or respond to changes that have occurred.」直接定义后立刻给出使用方向随后才展开 Editor#createShapes 等方法引用。概念、解释、代码每个概念后面都要跟一个可运行的示例。这是 tldraw 文档的第一原则You can access the editor in two ways:From the Tldraw componentsonMountcallback:function App() { return ( Tldraw onMount{(editor) { // your editor code here }} / ) }对照 editor.mdx 可以看到这个模式的完整落地先写「You can access the editor in two ways」再用编号列表给出onMount回调与useEditor钩子两种方式每种都配完整 TSX 代码。useEditor的例子还进一步演示了「组件必须渲染在 Tldraw 内部」这一限制function InsideOfContext() { const editor useEditor() // your editor code here return null } function App() { return ( Tldraw InsideOfContext / /Tldraw ) }渐进式披露从简单到复杂推进先写最常见的用例逐步增加复杂度把边界情况和高级模式留给后面的章节来自 persistence 文档的实例见 persistence.mdx先讲persistenceKeyprop最简单再讲 State snapshots更多控制然后讲storeprop完全控制最后讲 Migrations高级persistence.mdx 的实际组织完全遵循这一层级Local persistence → Snapshots → The store → Multiplayer sync → Migrations → Examples每一节都配完整的可复制代码。例如persistenceKey一节给出最小可用应用import { Tldraw } from tldraw import tldraw/tldraw.css export default function App() { return ( div style{{ position: fixed, inset: 0 }} Tldraw persistenceKeymy-document / /div ) }而store一节则展示如何用createTLStore与loadSnapshot自建存储import { useState } from react import { createTLStore, loadSnapshot, Tldraw } from tldraw export default function App() { const [store] useState(() { const store createTLStore() const saved localStorage.getItem(my-drawing) if (saved) { loadSnapshot(store, JSON.parse(saved)) } return store }) return Tldraw store{store} / }短段落段落保持 1-3 句。密集的文字块难以扫读要Meta information is information that is not used by tldraw but is instead used by your application. For example, you might want to store the name of the user who created a shape, or the date that the shape was created.不要Meta information is additional data that can be attached to shapes and is not used internally by tldraw but can be leveraged by your application for custom functionality. This could include things like the user who created the shape, timestamps, custom identifiers, or any other application-specific data that you want to associate with shapes but dont want to store in the props object.用表格组织相关信息用表格组织相关的方法、选项或概念MethodDescriptionEditor#setCameraMoves the camera to the provided coordinates.Editor#zoomInZooms the camera in to the nearest zoom step.Editor#zoomOutZooms the camera out to the nearest zoom step.editor.mdx 提供了一个大规模表格的实例把编辑器的全部能力按 Data、Interaction、View、State、Configuration、Output 六个区域组织成表每行指向对应的 SDK 功能文档Signals、Store、Tools、History 等。当信息真正具有平行结构时表格比列表更利于扫描。笔记与提示用 blockquote 承载重要的补充说明If all youre interested in is the state belowroot, there is a convenience method,Editor#getCurrentToolId, that can help.警告类信息使用更强的 Callout 语法Callout typewarning You must make sure that the tldraw version in your client matches the version on the server. /Callout这条警告对应 tldraw 同步架构中的一个真实约束客户端与服务器版本必须匹配否则记录 schema 可能无法互相迁移。交叉引用放开链接与其把一切讲透不如在文中内联引用相关概念For more information about how to synchronize the store with other processes, see the Persistence page.persistence.mdx 每节末尾都遵循此模式例如 store 一节以「See Store for details on store operations, listening to changes, queries, and transactions.」收尾把深水区留给专门页面。API 引用使用统一格式链接到 API 文档时使用MethodName模式Use the Editor#createShapes method.See TLInstancePresence for the full record type.MethodName使用类名#方法名的格式让读者一眼知道该去哪里查。指向可运行示例只要存在可运行示例就优先链接示例而不是只给代码片段For an example of how to create custom shapes, see our custom shapes example.persistence.mdx 的 Examples 一节集中演示了这一做法用带描述的精简列表指向 Persistence key、Snapshots、Local storage、Store events、Shape with migrations 五个可直接运行的示例。Nuggets技术博客文章Nuggets 是短篇技术文章讲的是我们如何解决有趣的问题。它们与参考文档不同——更像公司工程博客上的文章。不同的开场模式参考文档以定义开场Nugget 以「框定问题」开场——用一两句话告诉读者这篇文章在讲什么、为什么有趣然后才进入正文。参考文档开场The Editor class is the main way of controlling tldraws editor.Nugget 开场The tldraw SDK is all about making the little details work. If youve ever used dashed lines in tldraw, you might have noticed that the dashes always line up with the corners of your shape, the handles of a spline, or the start and end of an arrow. While this might seem like the obvious way that dashesshouldwork, you might be surprised to learn that SVG offers no such feature. We implement these perfect dashes entirely ourselves.Heres how it works.Nugget 开场要建立三样东西context我们在谈什么、tension存在一个难题或未满足的预期、stakes你为什么要在乎。目的是把技术文章扎根在某种叙事语境里——这些问题并非凭空出现而是来自 canvas 领域内的细节、行为、约定或「什么才感觉对」的期望。真正的问题是如何写出代码、说服计算机去做让体验感觉正确的事。这种工作常常违反直觉因而有趣因为它揭示了交互本身或相关技术的某些本质。这个问题在仓库中确实有对应实现getPerfectDashProps.ts 中getPerfectDashProps通过计算dashCount Math.floor(totalLength / dashLength / (2 * ratio))并对snap取整、处理outset/skip端点、为超短路径回退为单 dash来生成两端完整、间距均匀的strokeDasharray与strokeDashoffset。这正是「SVG 原生做不到、我们自己算」的代码级证据。结构Nugget 通常遵循这条弧线框定问题——这是关于什么的我们遇到了什么问题并解决了它为什么它难、违反直觉或有趣展示洞见——让解决方案成立的关键想法是什么走一遍实现——代码与解释逐步增加复杂度收尾——这段代码在代码库中的位置、权衡、文件链接以及未探索的领域、还能做什么、相关问题语气差异Nugget 比参考文档更温暖。它允许用 the trick is... 或 the insight is... 来标记关键想法穿插简短旁白说明某事为什么难或有趣展示旅程而非只给终点「我们试过 X但 Y 更好用」以观点收尾「这个权衡是值得的」它仍然不该漫谈或过度解释使用空洞的重要性断言this is crucial for...过于随意或玩笑化描述我们做了什么而不是告诉读者做什么Nugget 解释 tldraw 是如何解决某个问题的——它们不是教程。要把方案表述为「我们这样做」而不是命令式指令。不要The solution: dont decide immediately. Watch what the fingers do, then commit once the pattern is clear.Instead of guessing, implement a state machine that starts undecided.要Since we dont have enough information to know either way, we defer the decision. The gesture handler watches what the pointers do, then commits once we know enough to recognize the interaction pattern.Instead of guessing, we use a state machine that starts undecided and resolves as more information comes in.读者从观察我们的做法中学习而不是被指挥该做什么。示例开场过于突兀读起来像文档Tldraw calculates dash patterns that fit paths exactly. Complete dashes at both ends, even spacing throughout.更好从我们的经验开始When we added dashed lines to tldraw, we wanted them to look right—complete dashes at both ends, even spacing, corners that line up on rectangles. SVGsstroke-dasharraydoesnt do this.也不错框定我们遇到的问题Arrow routing sounds simple until you try it. Given two shapes, draw a line between them that doesnt pass through anything else. We spent a while getting this right.关于 Nugget 的更完整规则长度 800-1500 词、好选题特征、评估清单参见 blog-guide.md。两者配合使用时注意定位差异docs-guide 的 Nugget 章节讲「如何在参考文档体系内写短文」blog-guide 则给出完整的博客写作方法论。优先级文档写作的优先级排序准确性——代码必须能跑API 引用必须正确清晰度——读一遍就能懂简洁性——说一次继续前进删掉那些重复别的章节已经展示过的内容可扫读性——短段落、清晰的标题、大量的代码准确性排在第一位不是偶然。文档中的代码会被读者直接复制运行API 引用会被当作权威依据。persistence.mdx 中每个代码块都是完整可运行的组件import { Tldraw } from tldraw起、export default function App()止而 editor.mdx 中editor.run的示例甚至注释了选项语义{ history: ignore } // Changes wont affect undo/redo正是「代码必须能跑」的体现。避免冗余章节如果详细示例已经演示了某个模式就不要在「Common use cases」一节里用更短的片段重复相同信息。要么只保留详细示例首选只保留快速参考片段确保每个章节都带来真正的新信息不要先给出完整的 eraser 实现然后又在「Common use cases Eraser」里放同一段代码的删减版。要完整实现只展示一次。如果需要快速参考章节就做成表格指向详细示例。这与上文「放开链接」的原则一脉相承重复是文档成本链接是文档杠杆。评估检查清单审查文档时逐项检查开场句——是否立刻定义了这是什么东西代码示例——每个概念后面是否都有可运行的代码渐进式披露——复杂度是否逐步上升链接——相关概念是否被交叉引用可扫读性——短段落、清晰的标题语气与风格部分对照 VOICE.md 的检查清单主动语态、自信断言、代词使用、句首大写、诚实说明限制、人类声音——无空洞重要性断言、无尾随分词、无套路化过渡。配套文件与进一步阅读本指南是 tldraw 文档体系中的一环完整的写作规范由以下文件共同构成docs-guide.md——本文档SDK 参考文档的结构规则VOICE.md——语气与风格基础含代词用法、主动语态、避免 AI 写作痕迹等通用规则blog-guide.md——技术博客Nugget的完整写作方法apps/docs/content/docs——规范的实际产出地editor.mdx、persistence.mdx 等页面是本文每条规则的活样板getPerfectDashProps.ts——Nugget 开场示例中「完美虚线」问题的真实实现把这套规范用于实践时可以先选一篇 apps/docs/content/docs 下的页面用评估检查清单逐条对照再尝试把某个界面细节比如虚线对齐、箭头避障写成 Nugget 风格的短文检验自己是否真的掌握了「框定问题」与「展示洞见」这两步。规则本身不是目的——让开发者能快速扫读、放心复制、一次跑通才是这套规范的终点。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考