guia-entrevistas-de-programacion 内容创作规范：为 Astro 西班牙语技术面试指南编写 MDX 页面

guia-entrevistas-de-programacion 内容创作规范：为 Astro 西班牙语技术面试指南编写 MDX 页面

【免费下载链接】guia-entrevistas-de-programacion项目地址: https://gitcode.com/GitHub_Trending/gu/guia-entrevistas-de-programacion

本指南基于开源仓库guia-entrevistas-de-programacion的 CLAUDE.md 及其配套实现，系统讲解如何为这套基于 Astro 的西班牙语编程面试指南新增内容：包括内容文件的存放组织、frontmatter 字段约定、sidebar.order唯一性规则、/create-content技能的用法，以及配套的verify:content、check:links等验证命令。读完本文，你将掌握从新建.mdx文件、填写元数据到通过全部校验的完整实操流程。

仓库定位：一套内容即文档的面试指南

guia-entrevistas-de-programacion是一个基于Astro构建的西班牙语编程面试指南站点，覆盖数据结构与算法、设计模式、Clean Architecture、数据库、CI/CD 与最佳实践等常见面试主题。从 package.json 可以看到其技术栈为 Astro 7、Tailwind CSS 4、MDX 7，内容以.mdx文件的形式存放在 src/content/guide/ 目录中，并按主题分子目录组织。

CLAUDE.md 定义了该仓库内容创作的三条核心约定：

• 全部内容使用西班牙语书写；
• 内容文件是以.mdx结尾、按主题子目录组织的文档，位于src/content/guide/；
• frontmatter 中description必须为ASCII-only（无重音符号、无特殊字符），且每个文件夹内sidebar.order必须为唯一整数。

下面逐一展开说明这些约定在源码中的落地方式。

内容存放：src/content/guide/的目录组织

所有指南页面统一放在 src/content/guide/ 下，采用「主题目录 / 子主题文件」的嵌套结构：

• algoritmos-y-estructuras-de-datos/ —— 算法与数据结构（含complejidad-algoritmica.mdx、estructuras-de-datos.mdx等）；
• buenas-practicas/ —— 通用最佳实践（SOLID、DRY、KISS、YAGNI、GRASP、Clean Code 等）；
• buenas-practicas-en/ —— 按语言/框架区分的实践（Java、Python、React、Vue、Angular 等）；
• preguntas-frecuentes/ —— 常见面试问题，其中 javascript/ 下还有嵌套的专题文件。

内容集合的装载由 src/content.config.ts 定义：glob({ pattern: "**/*.mdx", base: "./src/content/guide" })递归收集该目录下所有 MDX 文件。也就是说，只要把.mdx文件放进src/content/guide/，就会被站点自动纳入内容集合，无需手工注册。

站点动态路由 src/pages/guia/[...slug].astro 通过getCollection("guide")读取全部条目并为每个条目生成静态页面，URL 由文件相对src/content/guide/的路径推导（entrySlug实现见 src/utils/guide.ts）。例如complejidad-algoritmica.mdx对应的访问路径即为/guia/algoritmos-y-estructuras-de-datos/complejidad-algoritmica。

frontmatter 字段约定：schema 级强制校验

CLAUDE.md 提到的字段并不是「约定俗成」，而是被 src/content.config.ts 中的 Zod schema 强制的——任何字段缺失或类型不符，都会在astro check/astro build阶段直接报错。完整 schema 如下：

const guide = defineCollection({ loader: glob({ pattern: "**/*.mdx", base: "./src/content/guide" }), schema: z.object({ title: z.string().min(1), description: z.string().min(1).max(180), category: z.string().min(1), section: z.string().min(1).optional(), sidebar: z.object({ label: z.string().min(1).optional(), order: z.number() }), references: z.array(referenceSchema), examples: z.array(exampleSchema).optional() }) });

对应到 CLAUDE.md 的约定，各字段要求如下：

以实际文件 complejidad-algoritmica.mdx 的 frontmatter 为例：

--- title: "Complejidad algoritmica" description: "Que es la complejidad algoritmica y como usar Big-O para analizar el tiempo y la memoria de un algoritmo." category: "Algoritmos y estructuras de datos" section: "Fundamentos" sidebar: label: "Complejidad algoritmica" order: 310 references: - label: "¿Qué es la complejidad algorítmica y con qué se come?" url: "https://medium.com/..." - label: "Introducción a Big-O Notation" url: "https://medium.com/..." ---

注意观察：这里的title与description都刻意省略了重音符号（algoritmica而非algorítmica），正是为了满足「description 必须 ASCII-only」的要求；而references中的label允许携带重音（¿Qué es…），说明该限制仅作用于description字段。

sidebar.order唯一性：为什么必须查重

CLAUDE.md 明确要求sidebar.order在每个文件夹内是唯一整数，并建议「先检查已有文件再取值」。这一规则的背后是侧边栏的排序算法——src/utils/guide.ts 中的byOrderThenTitle：

const byOrderThenTitle = (a: GuideEntryLike, b: GuideEntryLike) => { const orderDelta = a.data.sidebar.order - b.data.sidebar.order; if (orderDelta !== 0) return orderDelta; return a.data.title.localeCompare(b.data.title, "es"); };

即同一category下先按sidebar.order升序排列；当两个条目的order相同时，退化为按西班牙语title字典序排序。这意味着重复的order虽不会让构建崩溃，但会使排序结果依赖标题文本，产生非预期的顺序；而如果标题恰好相同，顺序甚至不再确定。因此新增内容时务必先查看目标目录下已有文件的order，选一个未占用的整数。

侧边栏的渲染与分组逻辑见 src/components/Sidebar.astro 与groupGuideEntries：条目按category分组、组内按上述规则排序，非顶层（slug 层级超过两层）的条目会被过滤，例如preguntas-frecuentes/javascript/cadena-de-prototipos这样的嵌套文件不会直接出现在侧边栏一级菜单中。

使用/create-content技能创建新内容

CLAUDE.md 明确指出：新建内容请使用/create-content技能，它涵盖了必需的 frontmatter 字段、正文结构、代码块约定、文件放置位置，以及写作前需要对照的检查清单。该技能位于仓库的.claude/skills/目录下（仓库还提供create-commit与create-pr技能，分别用于生成聚焦的 Conventional Commit 与准备 PR 草稿，详见 README.md）。

基于 CLAUDE.md 与现有文件的整体套路，新建一篇文章的推荐步骤是：

1. 确定主题并选择目标子目录，例如在 buenas-practicas/ 下新增kiss.mdx；
2. 阅读同目录已有文件，确定未占用的sidebar.order；
3. 编写.mdx文件：frontmatter 中title、description（ASCII-only）、category、sidebar.order、references为必填，examples可选；
4. 正文中复用 Callout.astro（提示框）与 CodeExample.astro（带标题的代码块）组件，并在文件顶部通过 MDX import 引入：

   import Callout from '../../../components/Callout.astro'; import CodeExample from '../../../components/CodeExample.astro';

   （import 路径需按文件层级使用相对路径，例如位于src/content/guide/algoritmos-y-estructuras-de-datos/时需要回退三层到达 src/components/）；

5. 运行下文介绍的验证命令，全部通过后再提交。

正文结构可以参考 complejidad-algoritmica.mdx：开头一段概念导读 → 分小节讲解 → 关键点用Callout强调 → 代码用CodeExample包裹 → 结尾给出实践建议。

内容验证：三把质量闸门

CLAUDE.md 与 README 共同定义了新增内容后的验证流程，全部通过npm脚本执行（见 package.json）：

1.npm run verify:content—— 迁移完整性校验

该命令执行 scripts/verify-content-migration.mjs，做两件事：

• 必填字段检查：遍历src/content/guide/下全部 MDX，确认每个文件都包含title、description、category、sidebar、references五个 key（通过 scripts/mdx-frontmatter.mjs 解析 frontmatter）；
• 与 README 索引对齐：脚本内置了一张requiredSections映射表，将 README 的历史章节（如Principios SOLID、Complejidad algorítmica）映射到对应的 slug；随后从 README.md 提取各章节的参考资料，逐一比对每个 MDX 的references是否完整迁移。缺失章节或缺失参考链接都会导致脚本以非零码退出。

2.npm run check:links—— 引用链接校验

执行 scripts/check-reference-links.mjs，默认校验每个 frontmatterreferences中 URL 的语法合法性（必须是http:或https:协议）。需要联网验证外部网站是否可访问时，加--fetch参数：

npm run check:links -- --fetch

它会用HEAD请求逐个探测，返回状态码 ≥ 400 即视为失效链接并报错。

3. 构建与测试

npm install npm run dev # 本地开发（需 Node.js >= 22.12.0） npm run build # astro check 类型检查 + astro build 静态构建 npm run test # Vitest 单元测试（含 content-schema、guide 排序等用例） npm run test:e2e # Playwright 端到端测试

其中npm run build会先执行astro check，frontmatter schema 的任何违规都会在这里被拦截。单元测试 tests/unit/content-schema.test.ts 与 tests/unit/guide.test.ts 分别覆盖 schema 约束与侧边栏排序逻辑，是理解sidebar.order行为的补充参考。

常见误区与注意事项

• description不能带重音：这是最常见的失误。即使标题可以带重音，description也必须写成纯 ASCII（complejidad algoritmica而非complejidad algorítmica）；
• sidebar.order要先查重：同目录下重复的order会把排序退化成语义不可控的标题字典序比较；
• references的 URL 必须合法：url字段需是完整 URL（带协议），且应指向真实存在的资源，否则check:links -- --fetch会报错；
• import 路径随层级变化：组件 import 使用相对路径，嵌套层级越深，回退的../越多，务必以 src/components/ 为基准核对；
• 不要遗漏 README 索引同步：由于verify:content会核对 README 章节与 MDX 的映射，大幅重构章节时需同步维护 scripts/verify-content-migration.mjs 中的requiredSections，或在 README 中保留对应的章节锚点。

小结

CLAUDE.md 用极简的三条约定，为guia-entrevistas-de-programacion的内容生产立下了可执行、可校验的规矩：西班牙语正文、src/content/guide/下的 MDX 组织、ASCII-only 的description与唯一整数sidebar.order。这些约定并非停留在文档层面，而是被 src/content.config.ts 的 Zod schema、src/utils/guide.ts 的排序算法、scripts/verify-content-migration.mjs 的校验逻辑层层落实。遵循本文梳理的 frontmatter 清单与验证流程，配合/create-content技能，即可稳定地产出通过全部检查的新指南页面。

【免费下载链接】guia-entrevistas-de-programacion项目地址: https://gitcode.com/GitHub_Trending/gu/guia-entrevistas-de-programacion