Skip to content

Latest commit

 

History

History
361 lines (258 loc) · 16.9 KB

README.md

File metadata and controls

361 lines (258 loc) · 16.9 KB
Raw

Content

The /content directory is where all the site's (English) Markdown content lives!

See the markup reference guide for more information about supported Markdown features.

See the contributing docs for general information about working with the docs.

Frontmatter

YAML Frontmatter is an authoring convention popularized by Jekyll that provides a way to add metadata to pages. It is a block of key-value content that lives at the top of every Markdown file.

The following frontmatter values have special meanings and requirements for this site. There's also a schema that's used by the test suite to validate every page's frontmatter. See lib/frontmatter.js.

versions

  • Purpose: Indicates the versions to which a page applies. See Versioning for more info.
  • Type: Object. Allowable keys map to product names and can be found in the versions object in lib/frontmatter.js.
  • This frontmatter value is currently required for all pages.
  • The * is used to denote all releases for the version.

Example that applies to GitHub.com and recent versions of GitHub Enterprise Server:

title: About your personal dashboard
versions:
  free-pro-team: '*'
  enterprise-server: '>=2.20'

Example that applies to all supported versions of GitHub Enterprise Server: (but not GitHub.com):

title: Downloading your license
versions:
  enterprise-server: '*'

You can also version a page for a range of releases. This would version the page for GitHub Enterprise Server 2.22 and 3.0 only:

versions:
  free-pro-team: '*'
  enterprise-server: '>=2.22 <3.1'

redirect_from

  • Purpose: List URLs that should redirect to this page.
  • Type: Array
  • Optional

Example:

title: Getting started with GitHub Desktop
redirect_from:
  - /articles/first-launch/
  - /articles/error-github-enterprise-version-is-too-old/
  - /articles/getting-started-with-github-for-windows/

See contributing/redirects for more info.

title

  • Purpose: Set a human-friendly title for use in the rendered page's <title> tag and an h1 element at the top of the page.
  • Type: String
  • Optional. If omitted, the page <title> will still be set, albeit with a generic value like GitHub.com or GitHub Enterprise.

shortTitle

  • Purpose: An abbreviated variant of the page title for use in breadcrumbs.
  • Type: String
  • Optional. If omitted, title will be used.

Example:

title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects

intro

  • Purpose: Sets the intro for the page. This string will render after the title.
  • Type: String
  • Optional.

permissions

  • Purpose: Sets the permission statement for the article. This string will render after the intro.
  • Type: String
  • Optional.

product

  • Purpose: Sets the product callout for the article. This string will render after the intro and permissions statement.
  • Type: String
  • Optional.

layout

  • Purpose: Wrap the page in a custom HTML layout.
  • Type: String that matches the name of the layout file, without an extension. For a layout named layouts/article.html, the value would be article.
  • Optional. If omitted, layouts/default.html is used.

children

  • Purpose: Lists the relative links that belong to the product/category/map topic. See Index pages for more info.
  • Type: Array. Default is false.
  • Required on index.md pages.

featuredLinks

  • Purpose: Renders the linked articles' titles and intros on product landing pages and the homepage.
  • Type: Object.
  • Optional.

The list of popular links are the links displayed on the landing page under the title "Popular." Alternately, you can customize the title "Popular" by setting the featuredLinks.popularHeading property to a new string.

Example:

featuredLinks:
  gettingStarted:
    - /path/to/page
  guides:
    - /guides/example
  popular:
    - /path/to/popular/article1
    - /path/to/popular/article2
  popularHeading: An alternate heading to Popular

showMiniToc

  • Purpose: Indicates whether an article should show a mini TOC above the rest of the content. See Autogenerated mini TOCs for more info.
  • Type: Boolean. Default is true on articles, and false on map topics and index.md pages.
  • Optional.

miniTocMaxHeadingLevel

  • Purpose: Indicates the maximum heading level to include in an article's mini TOC. See Autogenerated mini TOCs for more info.
  • Type: Number. Default is 3. Minimum is 2. Maximum is 4.
  • Optional.

allowTitleToDifferFromFilename

  • Purpose: Indicates whether a page is allowed to have a title that differs from its filename. For example, content/rest/reference/orgs.md has a title of Organizations instead of Orgs. Pages with this frontmatter set to true will not be flagged in tests or updated by script/reconcile-ids-with-filenames.js.
  • Type: Boolean. Default is false.
  • Optional.

changelog

  • Purpose: Render a list of items pulled from GitHub Changelog on product landing pages (ex: layouts/product-landing.html). The one exception is Education, which pulls from https://github.blog/category/community/education.
  • Type: Object, properties:
    • label -- must be present and corresponds to the labels used in the GitHub Changelog
    • prefix -- optional string that starts each changelog title that should be omitted in the docs feed. For example, with the prefix GitHub Actions: specified, changelog titles like GitHub Actions: Some Title Here will render as Some Title Here in the docs feed).
  • Optional.

defaultPlatform

  • Purpose: Override the initial platform selection for a page. If this frontmatter is omitted, then the platform-specific content matching the reader's operating system is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable. For example, most GitHub Actions runners use Linux and their operating system is independent of the reader's operating system.
  • Type: String, one of: mac, windows, linux.
  • Optional.

Example:

defaultPlatform: linux

defaultTool

  • Purpose: Override the initial tool selection for a page, where tool refers to the application the reader is using to work with GitHub (such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop) or the GitHub APIs (such as cURL or the GitHub CLI). If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable.
  • Type: String, one of: webui, cli, desktop, curl.
  • Optional.
defaultTool: cli

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.
  • Optional

*Note: the featured track is set by a specific property in the learning tracks YAML. See that README for details.

includeGuides

  • Purpose: Render a list of articles, filterable by type and topics. Only applicable when used with layout: product-sublanding.
  • Type: Array
  • Optional.

Example:

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. The topics are used to filter guides on some landing pages. For example, the guides at the bottom of this page can be filtered by topics and the topics are listed under the guide intro. Topics are also added to all search records that get created for each page. The search records contain a topics property that is used to filter search results by topics. For more information, see the Search contributing guide. Refer to the content models for more details around adding topics. A full list of existing topics is located in the allowed topics file. If topics in article frontmatter and the allow-topics list become out of sync, the topics CI test will fail.
  • Type: Array of Strings
  • Optional: Topics are preferred for each article, but, there may be cases where existing articles don't yet have topics or a adding a topic to a new article may not add value.

contributor

  • Purpose: Indicate an article is contributed and maintained by a third-party organization, typically a GitHub Technology Partner.
  • Type: Object. Properties are name and URL.
  • Optional.

Example:

contributor:
  name: ACME, inc.
  URL: https://acme.example.com/

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:

In single quoted leaves, a single quote character needs to be escaped. This is done by repeating the character.

As an alternative, you can change the single quotes surrounding the frontmatter field to double quotes and leave interior single quotes unescaped.

Autogenerated mini TOCs

Every article on the help site displays an autogenerated "In this article" section (aka mini TOC) at the top of the page that includes links to all H2s and H3s in the article by default.

  • To make the mini TOC include additional (or fewer) heading levels, you can add miniTocMaxHeadingLevel frontmatter to specify the maximum heading level. For example: miniTocMaxHeadingLevel: 4
  • To disable the mini TOC for a specific article, you can add this frontmatter: showMiniToc: false

Mini TOCs do not appear on product landing pages, category landing pages, or map topic pages.

Make sure not to add hardcoded "In this article" sections in the Markdown source or else the page will display duplicate mini TOCs.

Versioning

A content file can have two types of versioning:

  • versions frontmatter (required)
  • Liquid statements in content (optional)
    • Conditionally render content depending on the current version being viewed. See contributing/liquid-helpers for more info. Note Liquid conditionals can also appear in data and include files.

Free-pro-team vs. GitHub.com versioning

As of early 2021, the free-pro-team@latest version is only supported in content files (in both frontmatter and Liquid versioning) and throughout the docs site backend. It is not user facing. A helper function called lib/remove-fpt-from-path.js removes the version from URLs. Users now select GitHub.com in the Article Versions dropdown instead of Free, Pro, Team.

The convenience function allows us to continue supporting a consistent versioning structure under-the-hood while not displaying plan information to users that may be potentially confusing.

Filenames

When adding a new article, make sure the filename is a kebab-cased version of the title you use in the article's title frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add allowTitleToDifferFromFilename frontmatter.

Whitespace control

When using Liquid conditionals in lists or tables, you can use whitespace control characters to prevent the addition of newlines that would break the list or table rendering.

Just add a hyphen on either the left, right, or both sides to indicate that there should be no newline on that side. For example, this statement removes a newline on the left side:

{%- if currentVersion == 'free-pro-team@latest' %}

Links and image paths

Local links must start with a product ID (like /actions or /admin), and image paths must start with /assets. The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in lib/render-content/plugins/rewrite-local-links.

For example, if you include the following link in a content file:

/github/writing-on-github/creating-a-saved-reply

When viewed on GitHub.com docs, the link gets rendered with the language code:

/en/github/writing-on-github/creating-a-saved-reply

and when viewed on GitHub Enterprise Server docs, the version is included as well:

/en/[email protected]/github/writing-on-github/creating-a-saved-reply

There are transformations for image paths in GitHub Enterprise Server (versions 2.20-3.0) only. Once those versions are deprecation, there will no longer be any transformations for image paths. For more information, see /assets/images/enterprise/legacy-format/README.md.

Preventing transformations

Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, write the link using HTML and add a class of dotcom-only. For example:

<a href="/github/site-policy/github-terms-of-service" class="dotcom-only">GitHub's Terms of Service</a>

Sometimes the canonical home of content moves outside the docs site. None of the links included in lib/redirects/external-sites.json get rewritten. See contributing/redirects.md for more info about this type of redirect.

Index pages

Index pages are the Table of Contents files for the docs site. Every product, category, and map topic subdirectory has an index.md that serves as the landing page. Each index.md must contain a children frontmatter property with a list of relative links to the child pages of the product, category, or map topic.

Important note: The site only knows about paths included in children frontmatter. If a directory or article exists but is not included in children, its path will 404.

Creating new sublanding pages

To create a sublanding page (e.g. Actions' Guide page), 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
  3. (optional) Define which articles to include with includeGuides.

If using learning tracks, they need to be defined in data/learning-tracks/*.yml. If using includeGuides, make sure each of the articles in this list has topics and type in its frontmatter.