教程文档【免费下载链接】30-seconds-of-codeCoding articles to level up your development skills项目地址https://gitcode.com/gh_mirrors/30/30-seconds-of-code点击查看免费下载30 seconds of code 仓库中的所有文章Article都遵循统一的 Markdown 文件格式文件顶部是 YAML Frontmatter用于声明标题、语言、标签、封面等元数据下方是正文。本文以仓库中的模板文件 content/snippets/articles/snippet-template.md 为骨架结合 src/models/snippet.js、src/models/contentModel.js 等源码逐字段解释模板的含义、取值规则与底层处理逻辑帮助你写出能被站点正确收录、检索与发布的文章。模板总览一个文章文件由什么组成在 30 seconds of code 中一篇文章就是一个.md文件存放在 content/snippets/articles 目录正式文章位于其s/子目录中例如 content/snippets/articles/s/markdown-cheatsheet.md。模板文件全文如下--- title: My amazing story shortTitle: Amazing story language: javascript tags: [webdev] cover: image excerpt: A short summary of your story up to 140 characters long. listed: true dateModified: 2021-06-13 --- Write your story here.文件结构可以拆成两部分Frontmatter元数据区---包裹的 YAML 块声明文章的标题、语言、标签等 8 个字段正文区Frontmatter 之后的所有 Markdown 内容即文章的实际正文。从源码看这两部分会被分别消费src/lib/contentUtils下的解析工具负责把 Frontmatter 解析成结构化字段而正文则被 src/models/snippet.js 中的this.content读取见content字段赋值再通过enrichedContent等 getter 做进一步处理。Frontmatter 字段逐一拆解title文章标题title: My amazing storytitle是文章的完整标题。在 src/models/snippet.js 中this.title data.title直接对应此字段。它同时影响SEO 标题seoTitlegetter 会在标题中拼接语言名。对于javascript语言的文章若第一个标签是node则使用格式化后的标签名否则使用语言名JavaScript只有当title已包含该语言名时才不重复拼接。面包屑与推荐title是面包屑和推荐系统的显示文本来源之一。注意title与shortTitle不同前者用于完整展示后者用于卡片、内嵌预览等紧凑场景。shortTitle短标题shortTitle: Amazing storyshortTitle是文章的简短标题主要用于列表卡片、搜索自动补全和article-embed内嵌预览场景。在 src/models/contentModel.js 的previewTitlegetter 中可以看到Snippet 类型取this.title而 Collection 类型取this.shortTitle在asEmbedding()生成的h4内嵌链接中展示的也是shortTitle。language所属语言language: javascriptlanguage声明文章所属的编程语言或主题域取值对应 content/languages 目录下的语言定义文件如 content/languages/javascript.yaml、content/languages/python.yaml、content/languages/git.yaml 等。文章Article一般以javascript或webdev相关语言标记。该字段通过 src/models/language.js 的Language.find(this.languageId)解析为语言对象并驱动seoTitle中的语言前缀拼接。若language指向一个未注册的语言hasLanguage会返回false此时 SEO 标题与预览标签会退回到文章标题或主标签。tags标签列表tags: [webdev]tags是 YAML 数组声明文章所属的标签。在 src/models/snippet.js 中它被data.tags.split(;)从字符串拆分为数组第一个标签即primaryTag用于 SEO 标题与预览标签的格式化formatTag来自 src/lib/stringUtils.js。值得注意的实践第一个标签是主标签会影响 SEO 标题的拼接方式若包含站点配置中的更新日志标签settings.collections.updateLogTag该文章会被识别为更新日志条目isUpdateLog供updateLogs查询筛选标签同时也是搜索与推荐系统的重要信号src/lib/search 目录下的索引构建会消费标签信息。cover封面图cover: imagecover指定文章的封面图名称不含扩展名。封面图文件位于 content/assets/cover 目录例如laptop-view对应laptop-view.jpg。图片经构建流水线转换为 WebP 格式输出到 public/assets/cover。封面图的 URL 生成逻辑集中在 src/presenters/coverPresenter.js并通过 src/models/contentModel.js 的coverUrl、coverSrcset、coverFullUrl等 getter 暴露给模板使用。模板中的占位值image只是示意实际编写时请填一个真实存在的封面图文件名。excerpt摘要excerpt: A short summary of your story up to 140 characters long.excerpt是文章的简短摘要模板注释明确要求不超过 140 个字符。它最终会进入description字段用于站点的 SEO 描述seoDescription经StringUtils.stripHtml清理 HTML卡片与内嵌预览中的摘要文本formattedDescription搜索索引中的文本信号。listed是否列出listed: truelisted是布尔值控制文章是否出现在站点列表中。其语义在 src/models/contentModel.js 的listed()/unlisted()查询以及 src/models/snippet.js 的isListedgetter 中体现get isListed() { return this.listed this.isPublished; }即文章只有在listed: true且已发布isPublished时才被列出。listed: false的文章不会出现在公开列表但仍可被保留在仓库中。dateModified最后修改日期dateModified: 2021-06-13dateModified是文章的最后修改日期格式为YYYY-MM-DD。它在 src/models/snippet.js 中被解析为Date对象new Date(data.dateModified)并驱动三套关键逻辑排序byNew()按dateModified降序排列last30Days()筛选最近 30 天更新的内容发布/排期published()/scheduled()分别筛选dateModified早于/晚于当前时间的文章isPublished/isScheduled也是基于此判断——这意味着把dateModified设为未来日期即可实现排期发布展示dateFormatted、dateMachineFormatted、dateShortString分别提供长格式、ISO 格式与短格式的日期字符串。正文区Markdown 与特殊语法Frontmatter 之后就是正文。正文支持标准 Markdown参见 content/snippets/articles/s/markdown-cheatsheet.md 中的标题、段落、强调、列表、链接、图片、代码、引用、表格等基础语法此外还支持仓库自定义的扩展语法article-embed内嵌引用在正文中写入article-embed ref... title.../可以引用仓库内的其他内容条目。其处理逻辑见 src/models/snippet.js 的enrichedContentgetter源码用正则匹配article-embed ref(?ref[^#])(?hash#[^])* title(?title[^])/随后通过ContentModel.searchContentModels(ref)查找被引用条目若目标isEmbeddable则调用asEmbedding()生成带封面图、标题、描述的内嵌卡片 HTML否则替换为空字符串。从模板到集合文章与 Collection 的关系文章文件本身是 Snippet 模型而 content/collections 目录下的 YAML 文件如 content/collections/js/index.yaml负责把多个文章/代码片段组织成集合。集合模板 content/collection-template.yaml 展示了其字段结构slug: my-collection title: My awesome collection shortTitle: My collection listed: true snippetIds: - js/s/array-initialization - js/s/initialize-array-with-values - js/s/initialize-array-with-range - js/s/initialize-2d-array splash: plant-screen description: - Explain the collections topic in a few sentences. shortDescription: - A short description of your collection up to 140 characters long.可以看到snippetIds是文章/代码片段的 ID 列表定义集合的成员splash指定集合的封面图对应 content/assets/splash 下的图片description/shortDescription提供集合的完整与简短描述。文章与集合的关联关系由 src/models/collectionSnippet.js 维护src/models/snippet.js 通过collectionSnippets和collectionsgetter 反查文章所属的集合若文章设置了journeyId还会参与系列文章Journey的上一篇/下一篇分页previousJourneySnippet/nextJourneySnippet/journeyPagination。写作风格规范除了模板字段仓库的 CONTRIBUTING.md 还明确了内容写作的通用规范主要包括语言使用受众能理解的语言统一美式拼写句子尽量不超过 20 个单词每个句子只聚焦一个要点语气优先使用主动语态文档代码片段使用祈使句如 use this method阅读难度目标为 10 年级Grade 10阅读水平或以下避免行话和含混的习语方向性语言尽量用 previous / following 代替 above / below 来指代章节修改范围网站内容相关的改动只修改content/snippets或content/collections目录下的文件。校验与发布链路写完文章后其可发布性由源码中的查询逻辑决定isPublisheddateModified不晚于当前时间未来日期则处于已排期状态isListedlisted: true且已发布搜索索引docTokens、recTokens等字段会进入搜索与推荐系统相关逻辑见 src/lib/search 与 src/models/snippet.js 的recommendedSnippets确保文章可被检索与推荐。简而言之一篇合规的文章需要真实存在的cover图片、不超过 140 字符的excerpt、正确的language/tags取值以及符合格式的dateModified。对照 content/snippets/articles/snippet-template.md 模板逐项填写再参考同目录下的 content/snippets/articles/s/markdown-cheatsheet.md 等真实文章即可快速产出与站点体系兼容的内容。赞分享教程文档【免费下载链接】30-seconds-of-codeCoding articles to level up your development skills项目地址https://gitcode.com/gh_mirrors/30/30-seconds-of-code点击查看免费下载相关推荐30-seconds-of-code 内容创作指南HTML 文章片段模板与 frontmatter 字段深度解析30 seconds of code 内容创作指南HTML 文章片段模板与 frontmatter 字段深度解析 在 30 seconds of code 开教程文档30 seconds of code 贡献写作规范从风格指南到内容入库的实战手册30 seconds of code 贡献写作规范从风格指南到内容入库的实战手册 30 seconds of code 是一个由社区驱动的编程速查与文章项目教程文档30 seconds of code用 Git 提交信息模板commit.template统一团队提交规范30 seconds of code用 Git 提交信息模板commit.template统一团队提交规范 导读 在团队协作中提交信息commit m教程文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考