Livewire 官方文档写作规范全解基于 rules.md 的可落地风格指南【免费下载链接】livewireA full-stack framework for Laravel that takes the pain out of building dynamic UIs.项目地址: https://gitcode.com/gh_mirrors/li/livewire本篇指南系统解读 Livewire 仓库中 docs/rules/rules.md 这份官方文档写作规范——它不是介绍 Livewire 框架功能的教程而是定义Livewire 文档应该怎么写的元规则是贡献者在新增、重写或校对官方文档时必须遵守的风格契约。文中逐条拆解规则原文并结合仓库中 docs/wire-model.md、docs/actions.md 等已发布文档的实际写法验证每条规则的落地形态帮助你快速掌握 Livewire 文档的表述语气、结构组织、代码示例与排版约定从而写出与官方文档风格无缝一致的贡献内容。规则文档的定位docs/rules/目录是文档的宪法Livewire 仓库把文档写作规则单独放在 docs/rules/ 目录下与正式发布到文档站的.md页面如docs/quickstart.md、docs/actions.md物理隔离。这个目录里目前包含五个文件构成了一个完整的规则体系rules.md——总纲即本文解读的主体覆盖语气、结构、排版、排序与分组等全部写作维度Referencing file names in a sentance.md——专门约定在句子中如何引用文件路径Casing rules.md——约定三种典型场景下的大小写格式examples.md——约定代码示例中组件命名的用法questions.md——记录尚待决断的开放问题如示例中占位 URL 的写法。其中 rules.md 内部通过[[Referencing file names in a sentence]]与[[Casing rules]]两个双向链接Obsidian 风格 wiki 链接指向配套规则说明这三份文件在设计上就是相互引用的整体。下面按逻辑分组逐条展开。一、表述层面的写作规则语态、人称与代码示例rules.md 的前半部分集中规定了每一句话该怎么写共七条1. 何时以?php开头When do you start a file with ?php这条规则本身以提问形式写下对应的答案是当代码示例以 PHP 文件形式呈现、且文件开头没有?php标签就会无法运行或产生歧义时必须以?php开头。而当你展示的是 Blade 视图以指令或 HTML 开头、或 PHP 片段明显只是文件内部的一段比如属性声明时可以省略。仓库实际文档的写法可以印证这一判断标准——在 docs/actions.md 中展示单文件组件SFC完整代码时明确以?php开头?php // resources/views/components/post/⚡create.blade.php use Livewire\Component; use App\Models\Post; new class extends Component { public $title ; // ... };注意这里的?php不是孤立标签而是整文件代码示例的信号——它同时配合了文件路径注释// resources/views/components/post/⚡create.blade.php和完整的use导入语句。反之在 docs/wire-model.md 中展示的CreatePost组件示例同样以?php起始而后续仅展示 HTML 输入框时input typetext wire:modeltitle则直接是 Blade/HTML 片段不再出现 PHP 标签。2. 示例样式统一使用 TailwindAlways use tailwind in examples?文档示例中的 HTML/Blade 代码统一使用 Tailwind CSS 类来书写样式而不是内联style或自定义 CSS 类。这一约定保证了所有文档示例外观一致也便于读者在 Tailwind 生态中直接复制使用。需要说明的是这是一条针对文档示例的约定Livewire 运行时本身并不依赖 Tailwind仓库的 config/livewire.php 中也没有任何 Tailwind 配置项因此示例用 Tailwind纯粹是文档写作层的风格决策。3. 使用主动语态Use active voice.所有说明性文字使用主动语态active voice让动作主体清晰。对比两种写法主动推荐Livewire intercepts thesubmitevent and calls thesave()action on the server.被动避免Thesubmitevent is intercepted and thesave()action is called by Livewire.主动语态在仓库文档中随处可见例如 docs/actions.md 中的原句wire:submitintercepts thesubmitevent and calls thesave()action on the server——主语wire:submit、动词intercepts / calls、宾语event / action一清二楚没有任何被动结构。4. 使用第二人称单数 YouUse second-person singular (You)正文默认用 you 直接称呼读者营造一对一指导感。例如 docs/wire-model.md 中的原句To send property updates to the server as a user types into an input-field, you can append the.livemodifier towire:model——这里 you can append 是标准写法而不是 one can append 或 users can append。5. 允许用 We 引入概念步骤指令切换为 YouSometimes you can introduce a concept with first-person plural (We) and switch to You when giving step-by-step instructions这是对第 4 条的补充概念讲解阶段可以使用第一人称复数 we作者与读者共同探索的语气但一旦进入逐步操作指令必须切换为 you。这一从 We 到 You的转换是实现beginning to end叙事弧的关键手段见下文第七节。仓库文档中的典型形态是用 Lets explore a basic example of calling asaveaction:docs/actions.md这样的 Lets 句式引入示例随后立即转为 you 说明操作细节。6. 总是包含 import 语句Always include import statements凡是展示 PHP 类或函数的代码示例必须包含完整的use导入语句确保示例可以脱离上下文独立运行。这一点在 docs/actions.md 的示例中严格执行use Illuminate\Support\Facades\Auth; use Livewire\Attributes\Computed; use Livewire\Component; use App\Models\Post;同理 docs/wire-model.md 的CreatePost示例也包含use Livewire\Component;与use App\Models\Post;。这样做的价值在于读者无需猜测某个类来自哪个命名空间示例本身就是自洽的最小可运行单元。7. 保持一致但适当变换Be consistent, but switch it up (tone, filler transition text, using colons)整体风格必须前后一致统一使用主动语态、第二人称、Tailwind、完整 import但在过渡句、衔接语、标点使用如冒号引导示例上要有变化避免全文读起来像复制粘贴。换句话说一致性约束的是语法层面的规则变化性作用于修辞层面的节奏。例如同一篇文档里引导代码块时交替使用 Here is a simple example of ... :、For example, lets imagine ... :、To enable ... you can append ... : 等不同句式。二、可扫读性规则为不读字的读者优化Optimize for skimming (dont show wrong example first unless you have visual aid. People aint reading the words: this is wrong up-front)rules.md 用一句非常口语化的话点破了一个残酷现实大多数读者是在扫读skimming文档不是逐字阅读。因此文档组织必须让扫读者也能正确理解具体包括两条硬性要求不先展示错误示例——除非有可视化手段如高亮、红绿标注能明确传达这是错的否则先出现的就是读者会抄走的代码。展示错误示例必须搭配视觉辅助例如高亮注释!-- [tl! highlight] --或着色否则扫读者可能把错误代码直接复制进项目。结论前置——this is wrong up-front正确信息要第一时间出现不要在铺垫之后才给出。与这条规则配合的是 docs/rules/examples.md 中约定的示例组件命名清单它直接服务于扫读场景* CreatePost * UpdatePost * ShowPosts * SearchPosts * TodoList这份清单规定文档示例中反复出现的组件一律使用这些通用、自解释的名称CreatePost、UpdatePost、ShowPosts、SearchPosts、TodoList读者一看到CreatePost就能立刻明白这是一个创建文章的组件无需额外文字解释。docs/wire-model.md和docs/actions.md中的示例组件正是CreatePost、ShowPosts这些名字与 examples.md 完全一致。三、结构与排版规则页面骨架、代码块与 BlocksStart with H2s, H1 will be the title of the pageHave good syntax highlighting, use TorchlightHave good typography, use prose from tailwindWrite code examples first, then structure, then links and inlines, THEN paragraphs这一组规则定义了文档页面的骨架与皮肤1页面从 H2 开始H1 留给页面标题。每个文档页面本身是一个主题如 Actions、Wire Model页面标题H1由站点导航与模板统一生成参见 docs/__nav.md 中的{ uri: /docs/4.x/actions, file: /actions.md }映射结构因此正文第一行直接写 H2 小节不重复 H1。2语法高亮使用 Torchlight。所有代码块启用 Torchlight 高亮并支持[tl! highlight]行内标记来强调关键行。这在 docs/wire-model.md 中有直接应用input typetext wire:modeltitle !-- [tl! highlight] --!-- [tl! highlight] --注释即 Torchlight 的高亮指令渲染后该行会被高亮让扫读者第一时间锁定关键代码。3排版使用 Tailwind 的 prose 类。文档正文通过 Tailwind Typography 插件的prose类获得排版样式标题层级、间距、引用块样式等保证全站排版统一。这与第一节示例用 Tailwind是同一套技术栈的延续。4信息呈现顺序代码示例 → 结构 → 链接与内联 → 段落。这是整份规则中最重要的内容组织原则之一每个小节内优先展示可运行的代码示例其次交代结构如步骤列表再次给出链接与行内引用最后才是大段散文说明。反过来说最不重要的就是长篇段落——段落被排到最后天然符合扫读优先的哲学。观察 docs/actions.md 的开篇第一屏就是完整可运行的组件代码示例之后才是一段解释性文字正是这一顺序的体现。信息块Blocks的规范用法rules.md 还列出了文档中可用的信息块类型用于在正文之外插入辅助信息line break分隔线用于视觉分段tips提示warnings警告go here to learn more延伸阅读引导check out the screencast here视频教程引导Footer with more links页脚补充链接仓库文档中 warnings 的典型形态是 docs/wire-model.md 中那条醒目的告警块[!warning] Why isnt my component live updating as I type? If you tried this in your browser and are confused why the title isnt automatically updating, its because Livewire only updates a component when an action is submitted—like pressing a submit button—not when a user types into a field... Learn more about data binding.这条 warning 块完整示范了警告 原因解释 解决方案引导 延伸链接的组合形态正是 rules.md 所定义的go here to learn more式信息块的最佳实践。四、重复与beginning to end叙事弧Repeat yourselfWrite for a user to enter in anywhere and have context.Concept of beginning to endUsing We at beginning and transitioning to YouUsing more full code examples at the beginning1主动重复Repeat yourself。写作时要假设读者可能从文档的任意位置进入比如通过搜索引擎直接跳到中段小节因此关键概念要在每个出现的小节内自包含地重新解释一遍确保在任意处进入都有上下文。这就是 docs/wire-model.md 中Customizing the debounce小节会不厌其烦地重新说明默认 150ms 防抖的原因——读者可能没读过前面的Live updating小节。2beginning to end首尾呼应的叙事弧。每一篇文档都应呈现从开始到结束的完整旅程开篇使用 We或 Lets语气建立共同探索的语境并优先给出更多、更完整的全量代码示例——让读者先看到完整成品中后段切换为 You 的第二人称指令语气逐步给出可操作步骤结尾收束让读者完成从理解概念到上手操作的转变。这也解释了 docs/actions.md 的布局开篇即 Lets explore a basic example of calling asaveaction: 搭配完整组件代码随后各小节转为 you can pass the posts ID as a parameter 这类指令式表述。五、信息组织规则排序Order与分组GroupOrder by:Order from generic to specific (broad/niche)Order from happy path to edge cases (or commonness of needs/usage)Need for previous knowledge (one section might rely on another earlier section)Group by:Type of thing:ex.wire:loading.classis extremely popular.wire:loading.attris not, however it should be placed immediately after.classbecause its so popular文档小节的排列遵循两条编排原则排序原则Order by——三重标准递进从通用到具体generic → specific / broad → niche先讲适用范围广的内容再讲小众场景从 happy path 到 edge case先讲最常见、最顺利的用法再讲边界情况等价地按需求的常见程度排序commonness of needs/usage依赖前置知识需要依赖前面小节知识的小节必须放在被依赖小节之后。分组原则Group by——按内容类型聚合而不是按字母或随机顺序。规则给出的例子非常经典wire:loading.class是极其流行的用法而wire:loading.attr相对冷门但正因为它们属于同一类型loading 指令的修饰符attr必须紧跟在class之后哪怕它的热度远低于前者。也就是说类型相关性优先于热度排序。读者在阅读wire:loading.class时顺手就能发现.attr发现成本最低。六、配套规则文件名引用与大小写rules.md 通过 wiki 链接显式引用两份配套规则它们同样是写作时必须遵守的规范。在句子中引用文件路径Referencing file names in a sentance.md该文件给出了三种引用文件名的句式并明确指定偏好AWhen run, Livewire will create a new file in your app,app/Livewire/CreatePost.php, with the following contents:BWhen run, Livewire will create a newapp/Livewire/CreatePost.phpfile in your app, with the following contents:C首选When run, Livewire will create a file calledapp/Livewire/CreatePost.php, with the following contents:C 是唯一被认可的写法用 a file called路径 的句式把路径作为同位语嵌入句中路径前后有自然的语法边界扫读时不易与前后文字粘连也便于高亮渲染。大小写规则Casing rules.md该文件定义了三种上下文的大小写格式Title case标题大小写This Is A Title——用于页面标题、章节标题每个主要单词首字母大写Sentence case句子大小写This is a sentance.——用于正文句子仅句首与专有名词大写Bullet case列表项大小写This is a bullet——用于项目符号列表采用句子大小写风格首词大写、其余小写不以句号结尾。这套规则保证了标题、正文、列表在渲染后具有一致的大小写观感。七、尚待决断的开放问题questions.md规则体系还保留了未决问题记录目前登记了一项* What to use as a dummy URL: * ? https://application.test/?page2即文档示例中出现的占位 URL 应该统一用什么目前草案倾向https://application.test/?page2application.test是 Laravel 生态常用的本地测试域名?page2则贴合分页场景。这类开放问题会在后续编辑中定案并回填到 rules.md 中贡献者写文档时若遇到类似占位符可先遵循现有示例。八、规则在仓库中的落地验证rules.md 不是空谈仓库中的正式文档页面全部是它的实践产物。以下是规则到实文的对照表便于你写作时对照检查规则仓库实文示例完整 import 语句docs/actions.md 中的use Livewire\Attributes\Computed; use App\Models\Post;等以?php开头展示完整组件docs/actions.md 的单文件组件示例主动语态 第二人称docs/wire-model.mdyou can append the.livemodifierTorchlight 高亮docs/wire-model.md 中的!-- [tl! highlight] --warning 信息块 延伸链接docs/wire-model.md 的 Why isnt my component live updating as I type? 警告块示例组件命名规范docs/rules/examples.md 的CreatePost/ShowPosts等与 docs/wire-model.md、docs/actions.md 一致页面结构H1 由导航生成正文 H2 起始docs/__nav.md 的{ uri: /docs/4.x/xxx, file: /xxx.md }映射同时仓库根目录的 CLAUDE.md 补充了与文档写作相关的工程背景Livewire 是 Laravel 的全栈框架服务端渲染 DOM morph 更新src/为 PHP 源码、js/为前端源码文档站点版本映射见 docs/__nav.md当前为4.x。这些信息有助于你在写文档时判断示例代码的运行环境与版本语境。九、贡献者快速检查清单综合全文向 Livewire 文档提交内容前请逐项自查语气是否全程主动语态概念讲解用 We/Lets步骤指令用 You代码示例是否包含完整 import文件型示例是否以?php开头示例样式是否用 Tailwind是否先给完整示例、再给说明扫读体验是否避免了先错误后正确的写法关键代码是否加了[tl! highlight]高亮结构正文是否从 H2 开始H1 留给页面标题小节顺序是否符合通用→具体、happy path→edge case、依赖前置分组同类型的指令/修饰符是否聚合编排如wire:loading.class后紧跟.attr引用文件路径是否用 a file called路径 句式C 型标题用 Title case、正文用 Sentence case、列表用 Bullet case信息块提示/警告/延伸阅读是否按规范使用且每条警告都附带原因与解决方向一致性组件命名是否取自 examples.md 的固定清单占位 URL 是否符合 questions.md 的约定遵循这套规范你的文档贡献将与 Livewire 官方文档在语气、结构、可读性和可维护性上保持完全一致——这也是它被收录在 docs/rules/rules.md 的最终目的让所有贡献者写出读起来像 Livewire 官方文档的文档。【免费下载链接】livewireA full-stack framework for Laravel that takes the pain out of building dynamic UIs.项目地址: https://gitcode.com/gh_mirrors/li/livewire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考