为 guia-entrevistas-de-programacion 编写内容页面完整创作规范与实践指南【免费下载链接】guia-entrevistas-de-programacion项目地址: https://gitcode.com/GitHub_Trending/gu/guia-entrevistas-de-programacion这是一份面向开发者的内容创作指南围绕 guia-entrevistas-de-programacion 这一编程面试指南开源项目讲解如何按照项目既定规范为它新增一篇.mdx技术内容页面。读者读完可以掌握该项目的完整内容架构、Frontmatter 元数据规则、正文两种创作模式原理型与主题概览型、文件存放约定与写作前的自检流程并了解仓库中与之配套的 schema 校验、工具脚本与测试用例从而写出符合项目标准、可被构建与检索的内容。一、内容架构总览一切内容都是.mdx文件项目规定所有指南内容都以.mdx文件形式存放在src/content/guide/目录下。从仓库的集合加载配置 src/content.config.ts 可以看到这是通过 Astro Content Collections 的globloader 实现的const guide defineCollection({ loader: glob({ pattern: **/*.mdx, base: ./src/content/guide }), schema: z.object({ ... }) });这意味着任何放在src/content/guide/下、以.mdx结尾的文件都会被自动纳入guide集合并接受 Zod schema 的运行时校验。实际渲染时src/pages/guia/[...slug].astro 通过getCollection(guide)拉取全部条目entrySlug(entry)将文件名去掉.mdx后缀转换为 URL slug再交给DocsLayout与侧边栏渲染。因此创建新内容页面本质上就是在src/content/guide/下新建一个符合规定结构、通过 schema 校验的.mdx文件。所有内容页面必须精确遵循下文的结构。二、Frontmatter必填元数据与字段规则每个内容文件的头部都必须是 YAML Frontmatter其字段结构与默认值如下--- title: Full title of the article description: One sentence describing the topic. No accent marks — keep ASCII. category: Category name section: Section name sidebar: label: Short label (shown in sidebar nav) order: 21 references: - label: Display text for the link url: https://... ---各字段含义如下字段类型说明titlestring必填文章完整标题会渲染为页面的h1与titledescriptionstring必填一句话描述主题会写入meta namedescription并展示在正文标题之下必须是纯 ASCIIcategorystring必填分类名决定内容在侧边栏中归属哪个分组sectionstring可选所属章节名sidebar.labelstring可选侧边栏导航中显示的短标签缺省时回退为titlesidebar.ordernumber必填唯一整数决定在侧边栏中的排序references对象数组必填至少一项外部参考资料每个条目含label与url这些字段的约束并非口头约定而是由 schema 强制执行的。仓库中的 src/content.config.ts 为guide集合定义了完整的 Zod 校验title、description、category均为长度至少 1 的非空字符串其中description最长 180 字符sidebar为必填对象order必须是 number 类型references必须是对象数组每项label非空、url必须是通过z.string().url()校验的合法 URL另有可选的examples数组每一项可含title、description、language且必须提供title或description二者之一。也就是说references至少一条、sidebar.order必须是数字这两条硬性要求在构建时若不符合会直接报错而不是仅仅作为文档建议。三条关键规则description必须保持纯 ASCII不能带波浪号tildes、重音符号accent marks或任何特殊字符。注意这与正文语言无关——正文可以是西班牙语项目指南语言但元数据描述必须 ASCII。例如项目中的 dry.mdx 用Elimina la duplicacion de logica...而非duplicación。sidebar.order必须是唯一整数在写入之前先查看同一目录下已有文件的order取值范围避免冲突。references至少一条必须引用权威来源官方文档、知名书籍、可靠文章。项目示例中 dry.mdx 引用了The Pragmatic Programmer、refactoring.guru 等来源kiss.mdx 引用了 Wikipedia 与Clean Code。侧边栏如何消费这些字段sidebar.order与category的实际消费逻辑在 src/utils/guide.ts 中const byOrderThenTitle (a, b) { const orderDelta a.data.sidebar.order - b.data.sidebar.order; if (orderDelta ! 0) return orderDelta; return a.data.title.localeCompare(b.data.title, es); };条目先按sidebar.order升序排列order相同时再按标题以西班牙语 locale 排序随后groupGuideEntries以category为 key 分组groups.set(entry.data.category, ...)且只保留slug深度不超过两级的条目最终生成侧边栏的分组数据。在 src/components/Sidebar.astro 中分组标题category与条目标签sidebar.label或title被渲染为可折叠的导航结构。因此一个新页面的category取值决定了它出现在侧边栏的哪个分组而order决定它在组内的先后位置。例如目录 src/content/guide/buenas-practicas/ 下的dry.mdxorder 21与kiss.mdxorder 22同属 Buenas practicas 分类、按顺序相邻展示。三、正文模式一原理/原则型页面Principle/concept pages适合 DRY、KISS、SOLID 这类单一原则/概念的讲解。参照 dry.mdx 与 kiss.mdx 的模式结构固定为三段引言段无标题——首次提及时将原则名或缩写加粗例如DRY用 2–4 句话说明它是什么以及为什么重要。注意此段不需要标题。## Violacion del principio——先给出一个真实的坏代码示例fenced code block 并带语言标识随后用一小段文字说明问题出在哪里。## Aplicando [Principle name]——给出修正后的版本再用一小段说明改进点与原因。以 dry.mdx 为例其引言段为DRYsignificaDont Repeat Yourself(No te repitas). El principio establece que cada pieza de conocimiento o logica debe tener una unica representacion dentro del sistema...紧接着是## Violacion del principio展示三个各自重复乘法逻辑的价格函数再到## Aplicando DRY给出统一税率映射 单一calculatePrice函数的修正方案。这一先坏后好 简短解释的节奏就是原理型页面的标准模板。代码块规则必须始终包含语言标识符js、ts、python 等示例保持短小、自包含除非绝对必要否则不要写 import所有代码必须用英文书写标识符、变量名、函数名、类名、字符串值与行内注释都要用英文——这是项目的最佳实践无论指南正文使用什么语言代码始终使用英文这一通用语言。四、正文模式二主题概览型页面Topic overview pages适合需要覆盖多个子主题的知识总览型页面参照 bases-de-datos.mdx每个子主题使用###标题不强制作节顺序围绕主题自然组织结构。从仓库看src/content/guide/ 根目录下的backend.mdx、frontend.mdx、diseno-de-sistemas.mdx、patrones-de-diseno.mdx等都属于这类总览页面子目录 src/content/guide/algoritmos-y-estructuras-de-datos/ 与 src/content/guide/preguntas-frecuentes/ 下则存放更细分的专题。编写概览页时用###平铺各子主题即可前后顺序服从内容逻辑而非固定模板。五、文件放置与命名约定不同内容类型对应不同的目录具体如下表内容类型存放目录Buenas practicas / principios良好实践 / 原则src/content/guide/buenas-practicas/Algoritmos y estructuras算法与数据结构src/content/guide/algoritmos-y-estructuras-de-datos/Topic overview (general)通用主题概览src/content/guide/文件名一律使用小写 kebab-casenombre-del-tema.mdx。例如仓库中的dry.mdx、kiss.mdx、solid-principles.mdxsrc/content/guide/buenas-practicas/、complejidad-algoritmica.mdxsrc/content/guide/algoritmos-y-estructuras-de-datos/都符合这一约定。若内容属于具体语言/框架的实践如 Angular、React、Python可参考 src/content/guide/buenas-practicas-en/ 下的reactjs.mdx、python.mdx等组织方式。六、写作前 Checklist动手前的四项检查官方 skill 明确要求在写正文之前依次完成读取目标目录中的 1–2 个已有文件确认正在使用的order取值范围与category/section取值挑选一个能紧接该目录最后一个文件的order值顺序递增、保持唯一先写 Frontmatter再写正文不要在文件内添加任何尾部注释、作者备注或任务引用。从 src/utils/guide.ts 的排序逻辑可知order直接影响侧边栏显示顺序因此第 2 步的唯一性要求是真实约束而 src/content.config.ts 中的references: z.array(referenceSchema)也验证了至少一条引用的必要性。七、仓库配套的工具与测试支撑本项目并非只有文档层面的约定还提供了脚本与测试来保障内容质量Frontmatter 解析脚本scripts/mdx-frontmatter.mjs提供readMdxFrontmatter(path)用正则^---\n([\s\S]*?)\n---抽取 Frontmatter 块再解析其中的标量、列表与嵌套对象sidebar、references这种嵌套结构正是其解析目标供校验与迁移脚本复用。内容迁移校验scripts/verify-content-migration.mjs与 package.json 中的verify:content脚本node scripts/verify-content-migration.mjs对应用于检查内容迁移是否完整。链接检查scripts/check-reference-links.mjs对应check:links脚本校验references中的外部链接是否有效。单元测试tests/unit/content-schema.test.ts使用 Vitest 调用readMdxFrontmatter读取真实的 solid-principles.mdx断言其title、category、sidebar.order与references满足预期是先读取已有文件确认元数据这一 check 的自动化版本。构建与开发命令见 package.jsonnpm run dev启动本地开发服务器Astro 7 astrojs/mdxnpm run build会先执行astro check再做构建——也就是说Frontmatter 不合规的文件会在构建期被类型检查直接拦截。八、完整示例从零写一篇符合规范的内容页面综合以上全部规则一篇符合项目规范的原理型页面以 PRINCIPLE 为占位原则名示例代码为 JS应长这样--- title: PRINCIPLE — placeholder principle description: One sentence describing the topic. Keep it ASCII, no accent marks. category: Buenas practicas section: Principios sidebar: label: PRINCIPLE order: 23 references: - label: Authoritative reference 1 url: https://example.com/reference-1 - label: Authoritative reference 2 url: https://example.com/reference-2 --- **PRINCIPLE** is a software principle that says every piece of knowledge should have a single representation. It matters because duplicated logic becomes a maintenance trap. ## Violacion del principio js function a(x) { return x * 2; } function b(x) { return x * 2; }Both functions repeat the same multiplication logic. Any change to the rule must be applied in two places.Aplicando PRINCIPLEconst FACTOR 2; function applyFactor(x) { return x * FACTOR; }The logic now lives in a single place. Updating the rule requires editing only one line.对照前文逐项核验Frontmatter 包含全部必填字段且 description 为纯 ASCIIsidebar.order 取目录中不冲突的唯一整数references 提供了两条权威来源正文遵循引言加粗 → ## Violacion del principio → ## Aplicando PRINCIPLE三段结构代码块带 js 语言标识且全部为英文。把该文件以 kebab-case 命名存入 src/content/guide/buenas-practicas/ 目录即可通过 [src/content.config.ts](https://link.gitcode.com/i/b57d800396349cbc783bbff12f707585) 的 schema 校验经 [src/pages/guia/[...slug].astro](src/pages/guia/[...slug].astro) 渲染为独立页面并自动出现在侧边栏对应分组中。 ## 结语 从内容存放位置、Frontmatter 元数据规则、两种正文创作模式到文件命名、写作前检查清单与仓库配套的 schema/脚本/测试guia-entrevistas-de-programacion 提供了一整套可执行、可验证的内容创作规范。写作者只需严格遵循 .claude/skills/create-content.md[.claude/skills/create-content.md](https://link.gitcode.com/i/ee14e8069a36d27cc609d48e480e5590)中定义的流程并借助 npm run dev 本地预览、npm run build含 astro check验证 schema 合规性就能为这个西班牙语编程面试指南持续稳定地新增高质量内容页面。【免费下载链接】guia-entrevistas-de-programacion项目地址: https://gitcode.com/GitHub_Trending/gu/guia-entrevistas-de-programacion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考