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 的约定各字段要求如下字段类型说明titlestring至少 1 字符页面标题同时用于浏览器标题与侧边栏排序兜底descriptionstring1–180 字符必须为ASCII-only即不能包含á é í ó ú ñ ¿ ¡等重音或特殊字符它会渲染为页面描述、用于 SEO 元信息并作为导读段落展示categorystring侧边栏分组名称例如Algoritmos y estructuras de datossectionstring可选文档小节如Fundamentossidebar.labelstring可选侧边栏显示名称缺省时回退到titlesidebar.ordernumber组内排序整数每个目录内必须唯一referencesarray参考资料列表每项含label≥1 字符与url必须是合法 URLexamplesarray可选代码示例列表每项可含title/description/language且必须至少提供其一以实际文件 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 中的byOrderThenTitleconst 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 与现有文件的整体套路新建一篇文章的推荐步骤是确定主题并选择目标子目录例如在 buenas-practicas/ 下新增kiss.mdx阅读同目录已有文件确定未占用的sidebar.order编写.mdx文件frontmatter 中title、descriptionASCII-only、category、sidebar.order、references为必填examples可选正文中复用 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/运行下文介绍的验证命令全部通过后再提交。正文结构可以参考 complejidad-algoritmica.mdx开头一段概念导读 → 分小节讲解 → 关键点用Callout强调 → 代码用CodeExample包裹 → 结尾给出实践建议。内容验证三把质量闸门CLAUDE.md 与 README 共同定义了新增内容后的验证流程全部通过npm脚本执行见 package.json1.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 checkfrontmatter schema 的任何违规都会在这里被拦截。单元测试 tests/unit/content-schema.test.ts 与 tests/unit/guide.test.ts 分别覆盖 schema 约束与侧边栏排序逻辑是理解sidebar.order行为的补充参考。常见误区与注意事项description不能带重音这是最常见的失误。即使标题可以带重音description也必须写成纯 ASCIIcomplejidad algoritmica而非complejidad algorítmicasidebar.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考