贡献菜谱

如果您想为布局菜谱贡献一个示例,本页面将解释如何发布您的示例的步骤。

什么是好的菜谱?

任何有用的网页设计模式的最简化版本。您所包含的每一行 CSS 都应该有助于演示该模式,所以请删除任何纯粹为了美化示例而存在的内容。其思想是,人们可以获取该模式并将其用于具有自己风格的网站中。

一个菜谱包含

  • 一个实时示例,存储在CSS 示例 GitHub 仓库中。
  • 该示例的可下载版本,也存储在 CSS 示例仓库中。
  • 网站的CSS 布局菜谱部分中的一个页面,该页面应包含以下组件:
    1. 简介
    2. 依赖项
    3. 示例
    4. 决策
    5. 有用的回退或替代方法(如果相关)
    6. 可访问性考虑
    7. 浏览器兼容性(仅针对未完全支持的 CSS 属性)
    8. 其他资源

发布菜谱的步骤

要创建菜谱并将其添加到 CSS 布局菜谱,请遵循以下步骤:

  1. 构建模式
  2. 创建实时示例
  3. 创建可下载版本
  4. 提交包含您的示例的拉取请求
  5. 创建您的页面

1. 构建模式

在将您的示例变为菜谱之前,请先将您的模式创建为一个基本的 HTML 页面。思考您要演示什么,并尽可能保持简单。如果添加类名,请使用“container”或“item”等描述性词语。

请确保您已在多个浏览器、视口大小和设备上测试了 HTML 和 CSS。此外,请确保任何 CSS 样式都遵循可访问性指南。虽然使用支持有限的 CSS 属性是可以的,但请务必在创建页面时包含浏览器支持信息,尤其是在浏览器兼容性部分。在某些情况下,创建带有回退支持的示例的第二个版本可能会很有帮助。

2. 创建实时示例

菜谱页面上的实时示例,例如居中元素,以及 MDN 上的其他地方,允许读者操作代码并更改相关部分,而不会被所有代码淹没。您的菜谱将通过一个或多个示例进行演示。

分叉CSS 示例仓库,然后查看 css-cookbook 文件夹。那里有一个cookbook-template.html 文件。复制此文件并将其用作起点。将其保存到 css-cookbook 目录中,并为其取一个对您的模式有意义的名称。模板包含注释,可指导您在适当的位置添加各种部分。

此模板的重要部分如下:

  • 有一个用于编辑器面板的样式表,其中包含一些基本的 body 样式和一个用于编辑器功能的 JavaScript 文件。请保持这些文件不变。

  • <head> 包含两个样式块。第一个样式块用于读者无需更改即可操作示例的元素。第二个样式块包含读者可能想要操作的项目。我们通常将所有 CSS 添加到第一个块,然后选择要移动到第二个块的规则。第二个块中的规则应该是模式的基础,也许是读者可以更改 CSS 值并看到模式更新的规则。

  • 您需要将组件的 HTML 添加两次:首先在具有 preview 类的部分内,然后在使用 playable-html 类的 <textarea> 内。

  • 第二个 <head> 块中可编辑的 CSS 也必须复制到 playable-css 部分。

一个工作示例是 center.html,它嵌入在居中元素页面上。您可以使用它来查看如何正确添加各种部分。

如果您已经分叉了仓库,并且在您的示例中包含了我们的 CSS 和 JavaScript 文件,那么在浏览器中打开您的实时示例应该会显示一切都像在 MDN 页面上一样正常工作。

有用提示

  • 不要缩进文本区域内的 CSS 和 HTML;相反,将代码与行首对齐。这样在渲染时会更好看。
  • 如果需要任何图像,请将它们放在示例所在的目录中。欢迎使用任何已有的图像。
  • 您可以通过更改内联样式中的高度来调整文本区域的高度。

3. 创建可下载版本

由于示例包含我们所有的实时示例代码,我们希望为读者提供他们示例所需的代码,省略任何不必要的项。创建您的实时示例的副本,并将其名称添加 --download。例如,center.html 的下载版本是 center--download.html。此文件将类似于您的初始示例。它应该是一个基本的 HTML 页面,作为您的模式的单个 HTML 页面。

包含我们所包含样式表中的 body CSS 规则可能会很方便。请查看cookbook-template--download.html 作为指南;这些规则作为起点提供。

4. 提交包含您的示例的拉取请求

CSS 示例仓库上打开一个拉取请求 (PR)。这使我们能够在您创建页面之前帮助您对示例进行任何可能需要的更改。此外,示例需要上线才能被包含。这就是为什么首先创建代码示例,然后创建解释性指南是有意义的。在您的 PR 中,解释模式以及您正在演示的内容。请参阅我们的打开拉取请求的指南

5. 创建您的页面

您的示例 PR 合并后,打开一个拉取请求以在布局菜谱目录中创建一个新页面。使用我们的菜谱页面模板。模板解释了每个部分的要求,您可以参考其他菜谱示例以获取更多帮助。

请记住在主布局菜谱页面上添加指向您的新菜谱的链接。

如果您有任何问题或想让别人查看您的页面,请通过我们的任何沟通渠道与我们联系。

另见