Gatsby 中的 JavaScript 数据源实践：使用 gatsby-transformer-javascript-frontmatter 构建混合内容站点

Gatsby 中的 JavaScript 数据源实践使用 gatsby-transformer-javascript-frontmatter 构建混合内容站点【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby在 Gatsby 中Markdown 是内容型站点最主流的「根数据类型」但 JavaScript 同样可以作为内容源。本指南基于仓库中的using-javascript-transforms示例见 examples/using-javascript-transforms/README.md完整讲解如何在同一个站点中混用 Markdown 与 JavaScript 两种根数据源、如何通过gatsby-transformer-javascript-frontmatter从 JS 文件中提取 frontmatter、以及如何放弃默认的src/pages目录、改用gatsby-node.js全手动控制页面创建。读完本文你将掌握一种以 JS 组件直接充当页面 Markdown 走模板的混合建站模式并能理解其背后的 transformer 源码原理。示例概览一个混合 JavaScript 与 remark 的内容站点这个示例演示了 Gatsby 生态中 JavaScript 的多种用法它同时混用 JavaScript 与 remarkMarkdown 转换器使用 scss 与 bulma.io 作为样式方案在 layout 中使用 GraphQL并且借助 jsFrontmatter transformer即gatsby-transformer-javascript-frontmatter旧称gatsby-transformer-static-exports实现手动页面创建。整个站点围绕**两种根数据类型**展开基于 Markdown 的路由例如/a-first-post/内容位于 src/articles/2017-01-22-a-first-post/index.md基于 JavaScript 的路由例如 src/articles/2017-03-09-choropleth-on-d3v4/index.js。这里需要特别澄清基于 JavaScript 的路由与 src/templates/* 下的 React 模板组件、或 src/components/* 下的组件不是一回事——前者是内容本身一个直接导出组件 frontmatter 的 JS 文件后者是渲染框架。事实上大多数示例都会用一个 JavaScript 根数据类型来做首页本示例正是如此首页即 src/mainPages/index.js。目录结构解剖示例的完整布局如下examples/using-javascript-transforms/ ├── gatsby-config.js # 站点元信息与插件配置 ├── gatsby-node.js # slug 生成 全手动 createPages ├── package.json # 依赖与 npm scripts └── src/ ├── articles/ # 内容根数据源Markdown JavaScript 混排 │ ├── 2017-01-22-a-first-post/index.md │ ├── 2017-03-09-choropleth-on-d3v4/ │ │ ├── _choropleth.md # 下划线前缀不会自动建页可手动查询 │ │ ├── index.js # JS 根数据导出 frontmatter React 组件 │ │ └── style.scss │ └── 2017-05-30-choropleth-on-d3v4-alternate/ ├── components/ # 高阶组件、布局、站点导航等 │ ├── BlogPostChrome/ # 博客文章外壳高阶组件 │ ├── Layouts/ # master / blogPost / insetPage 三层布局 │ ├── HelmetBlock/ # SEO 头部 │ ├── PostPublished/ # 发布时间 │ ├── SiteLinks/ SiteNav/ SiteSidebar/ ├── mainPages/ # 无下划线、按 layoutType 区分的主页面 │ ├── 404.md about.md index.js contact.js ├── static/ # 全局样式与字体 └── templates/ # Markdown 内容的路由模板 ├── mdBlogPost.js # post 类型 └── mdInsetPage.js # page 类型对比默认的 Gatsby 站点这里刻意没有src/pages目录——原因在 README 中讲得很明确Gatsby 默认会对src/pages下任何 JavaScript 文件执行createPage本示例放弃该目录是为了换取对页面创建的完全控制详细实现见下文手动建页章节。插件配置两类数据源如何被拉取与转换gatsby-config.js 中的插件编排是整个示例的数据管线核心plugins: [ { resolve: gatsby-source-filesystem, options: { name: pages, path: ${__dirname}/src/mainPages/, }, }, { resolve: gatsby-source-filesystem, options: { name: articles, path: ${__dirname}/src/articles/, }, }, gatsby-transformer-javascript-frontmatter, { resolve: gatsby-transformer-remark, options: { plugins: [gatsby-remark-prismjs], }, }, gatsby-plugin-sass, ],逐个拆解其职责两个gatsby-source-filesystem实例分别指向src/mainPages/与src/articles/。用name字段区分不同文件集合pages/articles这是 Gatsby 多内容源的常规做法gatsby-transformer-javascript-frontmatter核心转换器负责把 JavaScript/TypeScript 文件中的frontmatter导出解析为JavascriptFrontmatter类型的 GraphQL 节点见下文源码原理gatsby-transformer-remark把 Markdown 转换为 HTML并挂载gatsby-remark-prismjs做代码高亮。注意其 plugins 选项只配了 prismjs——这正是文章类内容如_choropleth.md中 JavaScript 代码块能高亮显示的原因gatsby-plugin-sass支持 scss 编译配合 src/static/css/base.scss 与 bulma见 package.json 中的bulma0.9.0构成样式体系。在 siteMetadata 中还集中定义了站点标题、描述、作者、邮箱与 Twitter 信息供各页面的 GraphQL 查询统一引用...site_sitemetadatafragment。数据类型一Markdown 根数据Markdown 中的 frontmatter以第一篇博文 src/articles/2017-01-22-a-first-post/index.md 为例其 frontmatter 约定了一套站点自定义字段--- title: First Post About First Post written: 2017-01-22 updated: 2017-03-04 layoutType: post path: /a-first-post/ category: Beginnings description: From humble beginnings to... space? ---值得注意的约定有两点layoutType取值post或page决定了该节点被渲染成博文mdBlogPost还是内嵌页mdInsetPagepath显式声明路由路径如/a-first-post/而 slug另一个字段则由gatsby-node.js根据文件路径计算得出。slug 的生成逻辑在 gatsby-node.js 的 onCreateNode 中对MarkdownRemark与JavascriptFrontmatter两类节点统一计算 slug规则如下若文件名为index且位于子目录如2017-01-22-a-first-post/index.mdslug 为/${dirname}/即/2017-01-22-a-first-post/若文件位于根目录dir slug 为/${name}/其他情况文件名非 indexslug 为/${dir}/${name}/。生成的 slug 通过createNodeField挂在节点的fields.slug上供后续 GraphQL 查询过滤使用。模板Markdown 内容的 DRY 渲染README 指出大多数内容源包括 Markdown 路由都会经过模板处理src/templates/*在模板中我们可以组合dumb components哑组件以 DRY 的方式搭建页面结构。以 src/templates/mdBlogPost.js 为例模板通过查询变量$slug精确取到对应 Markdown 节点的html与 frontmatter再交给BlogPostChrome高阶组件统一渲染博客外壳export const pageQuery graphql query($slug: String!) { markdownRemark(fields: { slug: { eq: $slug } }) { html ...MarkdownBlogPost_frontmatter } site { ...site_sitemetadata } } 另一模板 src/templates/mdInsetPage.js 结构类似但套用InsetPageLayout用于layoutType: page的静态页面如 about、404。数据类型二JavaScript 根数据用 export 声明 frontmatterJavaScript 内容文件的写法与 Markdown 截然不同它本身就是一个 React 组件文件同时以命名导出的方式声明 frontmatter。看 src/articles/2017-03-09-choropleth-on-d3v4/index.js// this is one method to export data and make it usable elsewhere export const frontmatter { title: Choropleth on d3v4, written: 2017-03-09, updated: 2017-04-28, layoutType: post, path: /choropleth-on-d3v4/, category: data science, description: Things about the choropleth., }这套字段与 Markdown 的 frontmatter 字段完全同构title / written / updated / layoutType / path / category / description这正是两种数据源能在首页统一聚合、共用 GraphQL fragment 的前提。文件其余部分则是普通的 React 组件componentDidMount中用 d3 绘制美国各州 choropleth 地图render中把BlogPostChrome作为外壳并渲染来自_choropleth.md的 HTML 正文见下文下划线文件技巧。transformer 源码原理如何解析 JS 中的 frontmattergatsby-transformer-javascript-frontmatter的完整实现位于 packages/gatsby-transformer-javascript-frontmatter/src/gatsby-node.js其工作流程分三步范围过滤shouldOnCreateNode 只处理扩展名为js、jsx、ts、tsx的文件AST 解析用babel/parserbabylon把源码解析为 AST并根据扩展名选择flow或typescript插件见 options 配置提取 frontmatter通过babel/traverse遍历 AST捕获两种写法——module.exports.frontmatter ...形式的AssignmentExpression以及export const frontmatter ...形式的ExportNamedDeclaration见 traverse 逻辑。parseData函数递归支持对象、数组、模板字符串等字面量。只有当 frontmatter 非空时才会创建节点L110-L137节点类型为JavascriptFrontmatter并保留fileAbsolutePath供建页时直接require该文件。解析若抛错错误信息也会被存入节点供查询端处理而不是直接让构建失败。JavaScript 路由直接作为组件与 Markdown 走模板不同JavaScript 路由会被直接使用——createPages中把component指向path.resolve(edge.node.fileAbsolutePath)见 gatsby-node.js L103即页面组件就是内容文件本身。README 对此的提醒是这意味着每个 JavaScript 页面都需要自带部分路由级结构虽然有些痛苦但可以通过良好的高阶组件设计见 src/components/BlogPostChrome/index.js 与 src/components/Layouts/和 GraphQL fragment 来化解。下划线文件技巧为 JS 页面准备 Markdown 正文choropleth 示例中还有一个精巧的设计每个 JS 文章目录里都有一个_choropleth.md下划线前缀的 Markdown。之所以用下划线前缀是因为createPages查询里会遍历所有MarkdownRemark节点并为其建页而_choropleth.md这种文件名被约定性地排除在自动建页之外——于是它既能被 remark 转换为 HTML又不会产生多余的路由。在 JS 文章组件中通过 GraphQL 按固定 slug 手动拉取这段 HTML 并注入export const pageQuery graphql query choroplethOnD3v4($slug: String!) { markdownRemark( fields: { slug: { eq: /2017-03-09-choropleth-on-d3v4/_choropleth/ } } ) { html } javascriptFrontmatter(fields: { slug: { eq: $slug } }) { ...JSBlogPost_frontmatter } site { ...site_sitemetadata } } 见 index.js L200-L214这样一来正文用 Markdown 书写、代码逻辑用 JS 组件承载各取所长。手动建页不依赖 src/pages 的完整控制这是 README 最后强调、也是本示例最核心的工程决策。完整实现见 gatsby-node.js 的 createPages流程如下一次 GraphQL 查询同时取出allMarkdownRemark与allJavascriptFrontmatter各自带上frontmatter.layoutType、frontmatter.path与fields.slug对 Markdown 节点按layoutType分发post用mdBlogPost模板、page用mdInsetPage模板path取 frontmatter 中声明的路径context注入 slug对JavascriptFrontmatter节点做同样的分发但component直接指向文件绝对路径因为 JS 文件本身已是 React 组件无需模板再做非 React → React的转换。result.data.allJavascriptFrontmatter.edges.forEach(edge { let { frontmatter } edge.node if (frontmatter.layoutType post) { createPage({ path: frontmatter.path, // required // Note, we cant have a template, but rather require the file directly. // Templates are for converting non-react into react. jsFrontmatter // picks up all of the JavaScript files. We have only written these in react. component: path.resolve(edge.node.fileAbsolutePath), context: { slug: edge.node.fields.slug, }, }) } else if (frontmatter.layoutType page) { createPage({ path: frontmatter.path, component: path.resolve(edge.node.fileAbsolutePath), context: { slug: edge.node.fields.slug, }, }) } })代码注释清楚地说明了设计意图Gatsby 默认会对/pages目录下的 JavaScript 执行 createPages。我们刻意不建这个目录以便完全手动模式。见 gatsby-node.js L90-L93。同时所有页面都只通过 frontmatter 中的layoutTypepath两个字段驱动新增一篇文章只需添加内容文件并正确书写 frontmatter无需改动建页逻辑。高阶组件与 GraphQL fragmentJS 页面的 DRY 之道针对JS 页面需要自带路由级结构的痛点示例用BlogPostChrome高阶组件 fragment 给出了答案。该组件src/components/BlogPostChrome/index.js接收frontmatter与site两个 prop内部依次组合HelmetBlock注入页面 title 等 SEO 信息内容容器渲染this.props.children各页面自身的正文PostPublished展示 written / updated 时间。更重要的是它在同一文件内定义了供两种数据源共用的 fragmentL27-L50export const blogPostFragment graphql fragment MarkdownBlogPost_frontmatter on MarkdownRemark { frontmatter { title path layoutType written updated category description } } fragment JSBlogPost_frontmatter on JavascriptFrontmatter { frontmatter { title path layoutType written updated category description } } 由于两种节点的 frontmatter 结构一致Markdown 模板mdBlogPost与 JS 文章组件choropleth可以各自引用对应的 fragment保证字段集合永远同步这正是 README 中所说的以良好的高阶组件与 GraphQL fragments 管理 JS 页面的结构复杂性。布局侧则分为三层master.js全局 Helmet 与站点描述→blogPost.js/insetPage.js文章/内嵌页外壳→ 具体页面。首页跨数据源聚合src/mainPages/index.js 展示了如何把两类数据源在同一个页面里拧成一股绳其pageQuery同时查询allJavascriptFrontmatter与allMarkdownRemarkL89-L131渲染时把两边 edges 合并过滤出含written字段的节点用 lodashsortBy按updated || written倒序排列再按layoutType post过滤出文章列表生成标题、分类、描述与Read链接。也就是说无论文章来自 Markdown 还是 JS在首页都会以统一的卡片样式出现读者根本无从分辨内容源的差异。本地运行与构建在示例目录内执行 package.json 中定义的 scripts 即可npm install # 安装 gatsby、转换器、bulma、d3 等依赖 npm run develop # 启动开发服务器gatsby develop npm run build # 生产构建gatsby build npm run serve # 本地预览构建产物gatsby serve依赖清单中值得注意的是gatsby-transformer-javascript-frontmatter与gatsby-transformer-remark都使用了next版本标签跟随仓库当前迭代d3 固定在4.13.0以匹配文章代码的 v4 API如d3.queue()、d3.scaleQuantize()样式侧依赖bulma、node-sass与gatsby-plugin-sass。启动后可访问示例的两种路由形态Markdown 路由如/a-first-post/与 JavaScript 路由如/choropleth-on-d3v4/对照阅读即可直观感受两者的渲染差异。小结何时采用JS 根数据类型模式回看 README 的三点核心主张可以总结出本示例的价值两种根数据类型并存Markdown 适合长文与正文JS 根数据适合需要交互逻辑如 d3 可视化或程序化生成的页面二者通过同构的 frontmatter 统一建模模板 vs 直接组件Markdown 路由交给src/templates/*模板做 DRY 渲染JS 路由直接以文件为组件配合BlogPostChrome这类高阶组件与共享 fragment 控制重复结构手动建页模式放弃src/pages自动建页在gatsby-node.js中以layoutTypepath双字段驱动全部页面创建从而获得完全可控的路由生成流程相关设计讨论见 README 引用的 issue #1866 原型此处不再展开。该模式尤其适合博客 数据可视化 程序化页面混合的站点正文交给 remark 生态交互组件直接用 JS 承载页面编排全部收拢到gatsby-node.js一处既灵活又易于维护。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考