Cloudflare 中文文档
Style Guide
Cloudflare 中文文档
Style Guide
编辑这个页面
跳转官方原文档
Set theme to dark (⇧+D)
  1. Products
  2. Style Guide
  3. ...
  4. Content types
  5. Changelog

Changelog

​​ Purpose

The purpose of a changelog is to log or record notable changes.

​​ Tone

instructional, straightforward

​​ content_type

changelog

​​ Ownership

Developers and engineers maintain changelogs manually or via an automated process that their team owns. PCX provides a review but should not own creating or writing changelogs.

The structure of the page can differ depending on the frequency or type of page.

​​ Structure (single-page)

When creating a changelog, you need a Markdown page file and a corresponding YAML file in the /data/changelogs folder.

The combination of these files allows us to:

​​ Markdown file

Your Markdown file needs to have several special values to pull in the changelog information. These values are highlighted in the sample page.

​​ YAML file

The product-changelog component renders data that lives in a file within the /data/changelogs folder.

  • link string required

    • Relative path to the changelog page, such as "/queues/changelog/".

  • productName string required

    • Product name to display on the changelog product filter list, as well as other areas of the template.

  • productLink string required

    • Link to top-level docs for your product (helpful for context if someone is landing on the top-level changelog page)

  • productArea string required

    • Rollup grouping to surface related products together in context.

  • productAreaLink string required

    • Rollup grouping to surface related products together in context. Helps pull together related RSS feeds.

  • entries object required

    • publish_date date required

      • Date of published change, formatted as YYYY-MM-DD.

    • title string optional

      • Name of published change. Optional, but highly encouraged.

    • description string required

      • Markdown string that also follows YAML conventions. For multi-line strings, start the entry with |- and then type on an indented new line.

​​ Structure (multi-page)

In some cases, your changelog may have a separate page for each entry. The general structure is the same as the single-page changelog, but with a few small differences.

​​ Markdown files

​​ Top-level pages

For the top-level pages, you need the same frontmatter as the single-page example, but do not include any shortcodes in the body of the page.

​​ Individual entries

For each entry page, create a regular markdown page. These do not require a separate style of page or any adjustments.

​​ YAML file

Each individual entry needs an abbreviated entry in the changelog .yaml file.

  • publish_date date required

    • Date when the page was published, formatted as YYYY-MM-DD. For pages with scheduled changes, you should update this field when adding/updating entries, so that the changelog item gets placed at the top of the changelog list (and feed). You should not update this date when clearing all scheduled changes due to a release, since this change is not as relevant.

  • individual_page boolean required

    • Used to pull in the content from the page itself, as opposed to structured data in YAML.

  • link string required

    • Link to the individual page.

  • scheduled boolean optional

    • Should be included for scheduled pages. Because this component renders content on the underlying page, you should only have a) one scheduled entry per scheduled entry page and b) only a scheduled entry when the scheduled entry page has content.

  • scheduled_date date required

    • Should be included for pages with scheduled changes. Helps render the date of the upcoming change in the title, which provides more actionable information to folks scanning titles or the associated RSS feeds.

​​ Examples