Ceph

ceph.io

ceph.io 的静态网站。使用 Eleventy 构建。

要求

Node.js >18.x（包含 npm v10.x）

较早版本的 Node 和 npm 也可以工作，但我们建议使用这些版本以确保构建和环境之间的一致性。

我们在本地工作时使用 nvm 来管理 Node 版本，并在开始开发之前运行 nvm use 命令。

入门

安装

$ npm install

安装所有依赖项，如 package.json 中所述。其中大部分是 devDependencies，涵盖开发过程中使用的任何包。作为 dependencies 安装的包是那些旨在作为构建产品的一部分交付给最终用户的包。

了解更多

Eleventy 是一个基于 Node.js 构建的简单静态站点生成器。它是 Jekyll 和 Hugo 的快速且灵活的替代方案，并能很好地与现代 Web 项目并存。请访问 Eleventy 文档以获取详细的功能信息和示例项目。

本地开发

$ npm start

在 localhost:8080 处以开发模式运行站点，并监视更改。当文件发生变化时，站点将自动重新构建并刷新。

在底层，这正在使用 --serve 标志运行 Eleventy。有关更多信息，请参阅命令行用法文档。

为生产环境构建

$ npm run build

为生产环境构建站点。这将执行构建、优化并生成一个完整的构建包，以便部署到任何静态 Web 主机。

文件输出到 dist 目录，该目录已从版本控制中排除。

:warning: 重要提示： npm run build 操作仅适用于构建服务器和生产环境。在开发期间无需构建站点。未来当存在多种语言时，运行构建还将启动 scripts/prebuild.js，该操作负责将默认语言站点（en）中缺失的页面复制到所有支持的语言站点（由 _data/locales 确定）。此附加脚本确保生产环境中所有站点的内容一致性，在内容不可用时回退到英语。在支持的语言站点目录中生成的文件不应提交到版本控制。

调试

$ npm run debug

运行构建，并输出关于正在处理的文件和数据信息的详细日志。这在开发期间排查问题或通过 CI 部署时可能很有帮助。

更多信息请参阅调试文档。

部署

[TBC]

编写页面

页面数据

在所有页面的开头，都有一个用 --- 包裹的数据块。这被称为 frontmatter，并且会遵循相对于当前页面的特定 schema。

frontmatter 数据使用 YAML 格式以 key: value 对的形式编写。

Markdown 和 HTML

页面可以包含 Markdown 和 HTML 的混合内容。这意味着我们可以在同一文件中交替使用基本的内容格式化和更定制的 HTML 元素。

# Page title

A paragraph of text, Markdown style.

- Markdown list items
- Lists are great

<article class="bespoke">
  <h2>Stick to HTML</h2>
</article>

这里的注意事项是确保 Markdown 和 HTML 元素之间始终有清晰的界限。在单个内容块中混合使用两者将不起作用。

<!-- This won't work -->
<article>
  ## Trying for a Markdown heading (and failing)
</article>

<!-- This will -->
<article>

## All good here

</article>

要了解 Markdown 中可以实现的功能，请参阅 Markdown 指南。

添加链接

在整个站点中链接到页面的方式与在标准 HTML 站点中链接到页面的方式相同。

我们很可能使用 Markdown 的链接语法来链接到页面。我们选择的链接可以是相对链接或绝对链接。

让我们使用一个 blog-posts 页面（/blog/yyyy/blog-post）作为示例。如果我们想要链接到另一个博客文章页面，可以通过两种方式实现：

[Relative link to blog post](../blog-post/)

[Root relative link to blog post](/blog/yyyy/blog-post/)

如果我们需要链接到站点内的另一个章节/页面，我们可以使用上面所示的任意一种方法。../ 前缀可用于在站点树中向上遍历：

[Relative link to my parent](../)
[Relative link to my grandparent](../../)
[Relative link to a sibling of mine](../sibling-page/)

注意：这些不需要文件名 .md/.html 扩展名。

仅对站点外的链接使用绝对 URL：

[Absolute link to Ceph.io](https://ceph.io/)

动态值

我们可以在 Markdown 中插值这些动态值。例如，通过使用 {{ }} 语法，我们可以避免在页面标题标题中重复页面的 title 属性：

---
title: Don't repeat yourself
---

# Don't repeat yourself

变为：

---
title: Don't repeat yourself
---

# {{ title }}

短代码

短代码是可复用的代码片段，允许我们将复杂的标记封装到一个简洁、易用的用户界面中。

YouTube 视频播放器嵌入

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/vQF17UBU4RE"
  title="Ceph Tech Talk: Karan Singh - Scale Testing Ceph with 10Billion+ Objects 2020-10-01"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>

我们可以将此标记封装在一个短代码中，这样每次想要嵌入 YouTube 视频时就不需要重复它。它接受两个值，即视频的 id 和 title，并使用以下语法：

{% YouTube 'vQF17UBU4RE', 'Ceph Tech Talk: Karan Singh - Scale Testing Ceph with 10Billion+ Objects 2020-10-01' %}

我们使用 Nunjucks 块语法按名称调用短代码：{% YouTube %}。我们传递的第一个参数是视频的 id（例如 'vQF17UBU4RE'）。第二个（可选）参数将设置 iframe 嵌入的 title 属性（例如 'Ceph Tech Talk: Karan Singh - Scale Testing Ceph with 10Billion+ Objects 2020-10-01'）。

注意： 短代码参数对类型和空格敏感，因此应包含周围的 ' 引号。

我们现在拥有了 YouTube 嵌入代码的单一事实来源，使其易于维护，并可通过简单、干净的界面轻松复用。

提议更改

任何人都可以提出拉取请求以建议更改。但是，只有属于 GitHub Ceph 组织的人才能触发“Compiling Site”检查，这是拉取请求合并所必需的。不属于 GitHub Ceph 组织的人将无法触发“Compiling Site”检查，并且将被阻止合并任何更改。为了让他们更改得到审查，他们应联系指定的 Ceph 网站审查员，邮箱为 ceph-website@ceph.io。

:warning: ceph.io 网站有问题？

请通过电子邮件向 ceph-website@ceph.io 报告您遇到的任何网站问题。请包含问题的简要描述以及导致该问题的链接。