baker example page template

面包师示例页面模板

演示如何使用 Baker 构建工具构建和发布页面。

《洛杉矶时报》使用 Baker 创建在 latimes.com/projects 上发布的静态页面。 《纽约时报》系统依赖于一个类似于此的私有版本的存储库。此简化示例将暂存版本和生产版本发布到 Amazon S3 上的公共存储桶。

特征

• 实时更新本地测试服务器

• 使用 Nunjucks 制作 HTML 模板

• 使用 Sass 扩展 CSS

• JavaScript 与 Rollup 和 Babel 捆绑

• 使用 quaff 导入数据

• 基于结构化输入的动态页面生成

• 通过 GitHub Action 在每个push事件上自动将每个分支部署到暂存环境

• 通过 GitHub Action 在每个release事件上将按钮部署到生产环境

• Slack 消息通过 datadesk/notify-slack-on-build Github Action 中继每个部署的状态

要求

• Node.js 版本 12、14 或 16，但至少为 12.20、14.14 或 16.0。

• 节点包管理器

• git

文档

只需少量配置，您就可以使用此模板轻松发布页面。通过一些定制，您可以使其看起来像您想要的任何方式。本指南将向您介绍基础知识。

目录

• 创建新页面

• 探索存储库

• 访问资产

• 访问数据

• 动态页面

• 部署

• 全局变量

• 面包师.config.js

创建新页面

第一步是单击 GitHub 的“使用此模板”按钮，为自己创建存储库的副本。

系统会要求您为您的项目提供一个 slug。完成后，将在https://github.com/your-username/your-slug上提供一个新的存储库。

接下来，您需要将其克隆到您的计算机上才能使用代码。

打开终端并 cd 到代码文件夹。将项目克隆到您的文件夹中。这会将项目复制到您的计算机上。

 git 克隆 https://github.com/your-username/your-slug

如果该命令对您不起作用，可能是因为您的计算机设置不同，您需要使用 SSH 克隆到存储库。尝试在终端中运行此命令：

 git clone [email protected]:你的用户名/你的slug.git

存储库下载完成后，进入 your-slug 并安装 Node.js 依赖项。

 npm 安装

安装依赖项后，您就可以预览项目了。运行以下命令来启动测试服务器。

 npm 启动

现在在浏览器中访问localhost:3000 。您应该会看到一个可供自定义的样板页面。

从蓝图开始

另一种方法是使用 bluprint 创建新页面，bluprint 是路透社图形部门开发的命令行脚手架工具。

蓝图添加 https://github.com/datadesk/baker-example-page-template
mkdir 我的新页面cd 我的新页面
蓝图开始面包师示例页面

探索存储库

以下是从我们的页面模板克隆新项目时您会找到的标准文件和文件夹。您将比其他文件花费更多的时间来处理某些文件，但是对它们的用途有一个大致的了解是有好处的。

_数据

数据文件夹包含项目的相关数据。我们使用这个文件夹来存储每个项目所需的信息——比如它应该存在的 URL。您还可以在此处存储各种其他数据类型，包括.aml 、 .csv和.json 。

元数据

meta.aml文件包含有关页面的重要信息，例如标题、署名、slug、发布日期和其他字段。填写它可以确保您的页面正确显示并且可以被搜索引擎索引。所有属性的完整列表可以在我们的参考材料中找到。您可以扩展此选项以包含任意数量的选项。

_布局

此文件夹存储我们网站的基本模板和可重用的代码片段。当您开始时，您不太可能在此处进行任何更改。在更高级的用例中，您可以在其中存储跨多个页面重用的代码。

base.html

base.html 文件包含我们创建的每个页面上的所有基本 HTML。这里的示例在设计上是初级的。您可能希望在实际实施中包含更多内容。

_工作空间

工作区是您放置与项目相关但不需要在网络上发布的任何内容的地方。 AI 文件、代码片段、写作等等。这取决于你。

资产

用于存储媒体和其他资产，例如图像、视频、音频、字体等。它们可以通过static模板标签拉入页面。

脚本

JavaScript 文件存储在此文件夹中。 JavaScript 的主文件称为app.js ，您可以直接编写代码。通过npm安装的包可以像任何其他 Node.js 脚本一样导入和运行。您可以创建其他文件来在此文件夹中编写 JavaScript 代码，但必须确保该文件是从app.js启动的。

风格

我们的样式表是用 SASS 编写的，SASS 是一种功能强大的样式表语言，可以让开发人员更好地控制 CSS。如果您对 SASS 不满意，可以将纯 CSS 写入样式表中。

styles 文件夹包含一个样式表 ( app.scss )，您可以在其中将所有自定义样式添加到项目中，但有时您可能想要制作其他样式表并将它们导入到app.scss中。此示例项目仅包含模拟简单站点所需的最低限度。您可能希望在现实世界的实施中开始更多的工作。

面包师.config.js

baker.config.js文件是我们放置 Baker 用于服务和构建项目的选项的位置。它已在本文件的其他地方得到完整记录。除domain设置外，只有高级用户才需要更改此文件。

索引.html

您页面的默认模板。您将在此处布置页面。它使用 Nujucks 模板系统来创建 HTML。

package.json、package-lock.json

这些文件跟踪我们项目中使用的节点依赖项。当您运行npm install时，您添加的库将在此处自动跟踪。

.github

这是一个特殊的目录，用于存储 GitHub 用于与我们的项目和代码交互的文件。 .github/workflows目录包含处理我们的开发部署的 GitHub Action。您无需在此处编辑任何内容。

访问资产

作为部署过程的一部分，资产目录中的文件存储进行了优化和哈希处理。为了确保您对图像和其他静态文件的引用，您应该使用{% static %}标记。这确保了文件在发布时被大量缓存，并且图像的链接在所有环境中都有效。您会想将它用于所有照片和视频。

 <图>
  <img src="{% static 'assets/images/baker.jpg' %}" alt="贝克徽标" width=200>
</图>

访问数据

存储在_data文件夹中的结构化数据文件可通过模板标签或 JavaScript 访问。在此演示中，包含了一个名为example.json的文件来说明可能性。支持其他文件格式，例如 CSV、YAML 和 AML。

通过 Nunjucks templatetags

_data文件夹中的文件可按其名称在模板中使用。因此，使用_data/example.json ，您可以编写如下内容：

 {% 示例中的 obj %}
  {{ obj.year }}: {{ obj.wheat }}{% endfor %}

通过JavaScript

对于在 Baker 中构建项目的任何人来说，一个常见的需求是访问 JavaScript 文件中的原始数据。通常，这些数据会被传递到使用 d3 或 Svelte 编写的代码中，以在页面上绘制图形或创建 HTML 表格。

如果您正在访问的数据已经在您信任的 URL 上可用，那么这很容易。但如果不是，并且是您自己准备的数据怎么办？

可以访问 _data 文件夹中的记录。唯一需要注意的是，将此文件转换为可用状态的工作是您的责任。 d3-fetch是一个很好的库。

要以 Baker 理解的方式构建此文件的 URL，请使用以下格式：

 import { json } from 'd3-fetch';// 第一个参数应该是文件的路径 // 第二个参数 *必须* 是“import.meta.url” const url = new URL('../_data /example.json', import.meta.url);// 调用它 inconst data = wait json(url);

另一种方法是将数据作为script标记打印到模板中。 jsonScript过滤器接受传递给它的变量，对其运行JSON.stringify ，并将 JSON 输出到<script>标记内的 HTML 中，并在其上设置您作为参数传递的 ID。

 {{ 示例|jsonScript('示例数据') }}

一旦完成，您现在可以通过 JavaScript 中的 ID 检索存储在页面中的 JSON。

 // 获取使用您在 inconst dataElement = document.getElementById('example-data') 中传递的相同 ID 创建的元素 jsonScript;// 将该元素的内容转换为 JSON // 执行您需要对“data”执行的操作!const data = JSON.parse(dataElement.textContent);

虽然建议使用 URL 方法，但当您试图避免额外的网络请求时，此方法可能仍然是首选。它还具有不需要特殊库即可将.csv数据转换为 JSON 的额外好处。

动态页面

您可以通过将结构化数据源提供给baker.config.js文件中的createPages选项来生成无限数量的静态页面。例如，此代码片段将为example.json文件中的每条记录生成一个页面。

导出默认值{
 // ...为了说明这一点，上面的所有其他选项都已被排除
 createPages: createPages(createPage, data) {// 从 _data 文件夹中获取数据 const pageList = data.example;// 循环记录 for (const d of pageList) { // 设置将用于每个对象的基本模板。它位于 _layouts 文件夹 const template = 'year-detail.html';  // 设置页面的 URL const url = `${d.year}`;  // 设置将传递到模板上下文的变量 const context = { obj: d };  // 使用提供的函数渲染页面 createPage(template, url, context);}
  },};

这可用于使用单个模板创建类似/baker-example-page-template/1775/和/baker-example-page-template/1780/]的 URL。

部署

配置您的帐户

在部署由此存储库创建的页面之前，您需要配置您的 Amazon AWS 账户并向您的 GitHub 账户添加一组凭证。

首先，您需要在 Amazon 的 S3 存储服务中创建两个存储桶。一个用于您的暂存站点。另一个用于您的生产站点。对于这个简单的示例，每个都应允许公共访问并配置为提供静态网站服务。在一种更复杂的方案中，比如我们在《洛杉矶时报》运行的方案，这些存储桶可以与注册的域名相链接，并且通过身份验证方案将暂存站点从公众视野中屏蔽出来。

然后，这些存储桶的名称应存储为 GitHub“秘密”，可供部署站点的操作访问。您应该访问您的帐户或组织的设置面板。首先添加这两个秘密。

姓名	价值
BAKER_AWS_S3_STAGING_BUCKET	您的暂存存储桶的名称
BAKER_AWS_S3_STAGING_REGION	创建临时存储桶的 S3 区域
BAKER_AWS_S3_PRODUCTION_BUCKET	您的生产存储桶的名称
BAKER_AWS_S3_PRODUCTION_REGION	创建生产存储桶的 S3 区域

接下来，您应该确保您拥有来自 AWS 的密钥对，该密钥对能够将公共文件上传到您的两个存储桶。这些值也应该添加到您的秘密中。

姓名	价值
BAKER_AWS_ACCESS_KEY_ID	AWS 访问密钥
BAKER_AWS_SECRET_ACCESS_KEY	AWS 密钥

展示你的作品

此存储库中包含的 GitHub Action 将自动为每个分支发布一个暂存版本。例如，推送到默认main分支的代码将显示在https://your-staging-bucket-url/your-repo/main/ 。

如果您要创建一个名为bugfix的新 git 分支并推送您的代码，您很快就会在https://your-staging-bucket-url/your-repo/bugfix/上看到一个新的暂存版本。

发布您的作品

在实时发送页面之前，您应该确定 URL 的最终地址。这将设置存储桶中将发布页面的子目录。此功能允许《纽约时报》在同一个存储桶中发布大量页面，每个页面由不同的存储库管理。

第一步是将 URL 的 slug 输入到_data/meta.aml配置文件中。

 slug：您的页面 slug

确保你的子弹没有被拿走绝对不是一个坏主意。您可以通过访问https://your-production-bucket-url/your-slug/并确保它返回页面未找到错误来做到这一点。

如果您想在存储桶的根部发布页面，则可以将 slug 保留为空。

蛞蝓：

接下来，将更改提交到配置文件，并确保将其推送到 GitHub 上的主分支。

 git add _data/meta.aml
git commit -m“设置页面slug”
git推送原点主要

访问 GitHub 上存储库页面的发布部分。您可以在存储库的主页上找到它。

起草新版本。

您将在此处创建一个新的标签号。一个好的方法是从遵循语义版本控制标准的 xxx 格式编号开始。 1.0.0 是一个良好的开始。

最后，点击底部的绿色大按钮并发送版本。

等待几分钟，您的页面应该显示在https://your-production-bucket-url/your-slug/ 。

调试

Baker 测试服务器可以通过以下选项开始记录更详细的信息。

调试=1 npm 启动

要将日志限制为 Baker 运行：

调试=面包师:* npm start

如果您的构建不成功，您可以尝试通过终端在本地自行创建静态站点。如果页面构建出现错误，它们将被打印到您的终端上。

 npm 运行构建

全局变量

Baker 附带了一组在它创建的每个页面上都相同的全局变量，以及另一组基于当前创建的页面设置的特定于页面的变量。您可以使用这些变量有条件地向页面添加内容或根据当前页面过滤掉不相关的数据。

NODE_ENV

NODE_ENV变量始终是两个值之一： development或production 。它对应于页面上正在运行的构建类型。

当您运行npm start时，您处于development模式。当您运行npm run build时，您处于production模式。

仅当您处于development模式时，这对于向页面添加内容最有用。

 {% if NODE_ENV == 'development' %}<p>您永远不会在实际网站上看到此内容！</p>{% endif %}

DOMAIN

DOMAIN变量将始终与baker.config.js中传递的domain选项相同，如果未传递，则为空字符串。

PATH_PREFIX

PATH_PREFIX变量将始终与baker.config.js中传递的pathPrefix选项相同，如果未传递，则为单个正斜杠 ( / )。

page.url

当前页面的项目相对 URL。如果baker.config.js文件中提供了pathPrefix，则将包含pathPrefix - 换句话说，它将考虑正在完成的任何项目路径并指向项目中的正确页面。

page.absoluteUrl

当前页面的绝对 URL。这会将domain 、 pathPrefix和当前路径组合成一个完整的URL。当前用于输出规范 URL 和社交<meta>标签的所有 URL。

 <link rel="canonical" href="{{ page.absoluteUrl }}">

page.inputUrl

这是用于创建此页面的原始模板相对于当前项目目录的路径。如果您的 HTML 文件位于page-two/index.html ，则page.inputUrl将为page-two/index.html 。

page.outputUrl

这是为创建此页面而输出的 HTML 文件相对于_dist文件夹的路径。如果您有一个位于page-two.html的 HTML 文件， page.outputUrl将为page-two/index.html 。

面包师.config.js

我们从事的每个 Baker 项目的根目录中都包含一个baker.config.js文件。该文件负责将信息传递给 Baker，以便它可以正确构建您的项目。

导出默认值{
  // 资产所在目录
  资产：“资产”，

  // 创建页面
  创建页面：未定义，

  // 数据目录
  数据：'_data'，

  // 用于构建路径的可选自定义域
  域：未定义，

  // 每个 JavaScript 入口点的路径或一组路径
  入口点：'scripts/app.js',

  // 整体输入目录，通常是当前文件夹
  输入：process.cwd(),

  // 模板布局、宏和包含所在的位置
  布局：'_layouts'，

  // 一个对象，其中包含全局变量的键和值
  // 传递给所有 Nunjucks 模板
  nunjucks变量：未定义，

  // 一个键（名称）+值（函数）的对象，用于添加自定义
  // 过滤 Nunjucks
  nunjucksFilters：未定义，

  // 一个键（名称）+值（函数）的对象，用于添加自定义
  // Nunjucks 的标签
  nunjucks标签：未定义，

  // 编译后的文件输出到哪里
  输出：'_dist'，

  // 添加到每个解析路径开头的前缀，如何添加
  // 蛞蝓工作
  路径前缀: '/',

  // 一个可选目录，用于放置所有资源，很少使用
  静态根：''，}；

选项

资产

默认值： ”assets”

这告诉 Baker 将哪个文件夹视为资产目录。您可能不必更改此设置。

创建页面

默认值： undefined

createPages是一个可选参数，可以使用项目中的数据和模板动态创建页面。

导出默认值{
  // …

  // createPage - 传入模板、输出名称和数据上下文
  // data - `_data` 文件夹中准备好的数据
  createPages(createPage, data) {for (const title of data.titles) { createPage('template.html', `${title}.html`, {context: { title }, });}
  },};

数据

默认值： ”_data”

data选项告诉 Baker 将哪个文件夹视为其数据源。您可能不需要更改此设置。

领域

默认值： undefined

domain选项告诉 Baker 在构建绝对 URL 时要使用什么。 bakery-template将其预设为https://www.latimes.com 。

入口点

默认值： ”scripts/app.js”

entrypoints选项告诉 Baker 将哪些 JavaScript 文件视为脚本包的起点。这可以是文件或文件全局的路径，从而可以同时创建多个包。

输入

默认值： process.cwd()

input选项告诉贝克将哪个文件夹视为整个项目的主目录。默认情况下，这是baker.config.js文件所在的文件夹。您可能不需要设置它。

布局

默认值： ”_layouts”

layouts选项告诉 Baker 模板、包含内容和宏的位置。默认情况下，这是_layouts文件夹。您可能不需要设置此项。

Nunjucks过滤器

默认值： undefined

您可以使用nunjucksFilters传入您自己的自定义过滤器。在对象中，每个键是过滤器的名称，函数值是使用过滤器时调用的函数值。

导出默认值{
  // ...

  // 传递一个过滤器对象以添加到 Nunjucks
  nunjucksFilters: {square(n) { n = +n;  返回n*n；}
  },}

 {{值|平方}}

修女标签

默认值： undefined

您可以使用nunjucksTags传入您自己的自定义标签。它们与过滤器的不同之处在于它们使输出文本或 HTML 块变得更容易。

导出默认值{
  // ...

  // 传递一个过滤器对象以添加到 Nunjucks
  nunjucksTags: {doubler(n) { return `<p>${n} 加倍为 ${n * 2}</p>`;}
  },};

 {% 加倍值 %}

输出

默认值： ”_dist”

output选项告诉 Baker 当npm run build运行时将文件放在哪里。默认情况下，这是_dist文件夹。您可能不需要设置此项。

路径前缀

默认： ”/”

pathPrefix告诉 Baker 将什么路径前缀添加到它构建的任何 URL 中。如果还传递了domain ，则在构建绝对URL时它将与pathPrefix结合起来。您通常不会手动设置它 - 它在部署期间用于使用项目 slugs 构建 URL。

静态根

默认： ””

staticRoot选项指示 Baker 将所有资源放入附加目录中。这对于需要在每个页面上具有唯一的 slugs 而无需嵌套的项目非常有用，从而允许它们共享静态资源。然而，这是一种特殊情况，需要自定义部署设置。如果没有充分的理由，请勿尝试使用此功能。