diff --git a/content/README.md b/content/README.md index 69da2ee8a7..48c017fe14 100644 --- a/content/README.md +++ b/content/README.md @@ -21,6 +21,10 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work - [`miniTocMaxHeadingLevel`](#minitocmaxheadinglevel) - [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) - [`defaultPlatform`](#defaultplatform) + - [`learningTracks`](#learningTracks) + - [`includeGuides`](#includeGuides) + - [`type`](#type) + - [`topics`](#topics) - [Escaping single quotes](#escaping-single-quotes) - [Autogenerated mini TOCs](#autogenerated-mini-tocs) - [Versioning](#versioning) @@ -29,6 +33,7 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work - [Whitespace control](#whitespace-control) - [Links and image paths](#links-and-image-paths) - [Preventing transformations](#preventing-transformations) +- [Creating new sublanding pages](#creating-new-sublanding-pages) ## Frontmatter @@ -186,6 +191,39 @@ Example: defaultPlatform: linux ``` +### `learningTracks` +- Purpose: Render a list of learning tracks on a product's sub-landing page. +- type: `String`. This should reference learning tracks' names defined in [`data/learning-tracks/*.yml`](../data/learning-tracks/README.md). +- Optional + +**Note: the first learning track is by-default the featured track.* + +### `includeGuides` +- Purpose: Render a list of articles, filterable by `type` and `topics`. Only applicable when used with `layout: product-sublanding`. +- Type: `Array` +- Optional. + +Example: + +```yml +includeGuides: + - /actions/guides/about-continuous-integration + - /actions/guides/setting-up-continuous-integration-using-workflow-templates + - /actions/guides/building-and-testing-nodejs + - /actions/guides/building-and-testing-powershell +``` + +### `type` +- Purpose: Indicate the type of article. +- Type: `String`, one of the `overview`, `quick_start`, `tutorial`, `how_to`, `reference`. +- Optional. + +### `topics` +- Purpose: Indicate the topics covered by the article. +- Type: `String` +- Optional. + + ### Escaping single quotes If you see two single quotes in a row (`''`) in YML frontmatter where you might expect to see one (`'`), this is the YML-preferred way to escape a single quote. From [the YAML spec](https://yaml.org/spec/history/2001-12-10.html): @@ -274,3 +312,15 @@ Sometimes you want to link to a Dotcom-only article in Enterprise content and yo ``` Sometimes the canonical home of content moves outside the docs site. None of the links included in [`lib/redirects/external-sites.json`](/lib/redirects/external-sites.json) get rewritten. See [`contributing/redirects.md`](/contributing/redirects.md) for more info about this type of redirect. + + +### Creating new sublanding pages + +To create a sublanding page (e.g. [Actions' Guide page](https://docs.github.com/en/actions/guides)), create or modify an existing markdown file with these specific frontmatter values: + +1. Use the sublanding page template by referencing it `layout: product-sublanding` +2. (optional) Include the learning tracks in [`learningTracks`](#learningTracks) +3. (optional) Define which articles to include with [`includeGuides`](#includeGuides). + +If using learning tracks, they need to be defined in [`data/learning-tracks/*.yml`](../data/learning-tracks/README.md). +If using `includeGuides`, make sure each of the articles in this list has [`topics`](#topics) and [`type`](#type) in its frontmatter. diff --git a/data/README.md b/data/README.md index 22263c674c..7c817fc8a8 100644 --- a/data/README.md +++ b/data/README.md @@ -27,3 +27,7 @@ Webhook payload JSON files are used in the [`webhook events docs`](../content/de ## ui.yml `ui.yml` contains localized strings used in HTML layouts. + +## Learning Tracks + +Learning tracks are a collection of articles that help you master a particular subject. See [learning-tracks/README.md](learning-tracks/README.md). \ No newline at end of file diff --git a/data/learning-tracks/README.md b/data/learning-tracks/README.md new file mode 100644 index 0000000000..ec0f70309e --- /dev/null +++ b/data/learning-tracks/README.md @@ -0,0 +1,3 @@ +# Learning Tracks (aka Learning Paths) + +Learning tracks are a collection of articles that help you master a particular subject. Learning tracks are defined on a per-product basis. \ No newline at end of file