An article can be defined as being relevant to one or more topics by having those topics listed in the article's frontmatter. For example:
---
title: "Managing branches in your repository"
topics:
- "GitHub"
- "Git"
- "Repositories"
---
For more information on adding topics to an article see, "Using YAML frontmatter". For a list of all allowed topics, see allowed-topics
.
Topics for all content types
- Use nouns as topics
- Topics help people meaningfully group content
- When possible, use more specific topics that are relevant and not just broad topics. For example,
REST
orGraphQL
rather than justAPI
- Ensure that topics on similar articles are consistent so that people who filter by a topic get all of the relevant articles. For example, all articles about CI should have the
CI
topic plus more specific topics - Avoid ambiguous topics. For example,
Actions
may not be a useful topic within the Actions product since it could refer to the product GitHub Actions or the product element called an action
- When possible, use more specific topics that are relevant and not just broad topics. For example,
- Topics add value beyond and do not replicate the article’s title, type, or category
- For example, within the Actions product,
Actions
does not add value since someone in this section of the docs would already know that they are looking at Actions docs
- For example, within the Actions product,
- Use
Fundamentals
for articles related to the core concepts of a product area.- Use:
Fundamentals
in an article like “Introduction to GitHub Actions” - Avoid:
Actions
in an article like "Introduction to GitHub Actions"
- Use:
- Commonly-recognized abbreviations can be used, but obscure or ambiguous abbreviations should be avoided
- Use:
CI
instead ofContinuous integration
- Avoid:
AS
instead ofAdvanced Security
- Use:
- Use the short forms of GitHub product names
- Use:
Actions
instead ofGitHub Actions
- Use:
Checklist for choosing topics
Consider these questions to help choose topics for an article. Not every article will have a topic for each item in the checklist.
- What is the feature or product area?
- Example:
Enterprise
Is the article about a sub-feature (unless the product name matches the feature name)? - Example:
Dependabot
- Example:
- Is the feature part of a restricted program?
- Example:
Advanced Security
- Example:
- What element of the feature or product is the article?
- Example:
Organizations
- Example:
- What is the broad purpose of the article?
- Example:
Permissions
- Example:
- What programming languages, package managers, or ecosystems does the article explicitly address? Only include these topics if it adds value to someone filtering the docs, not just if an article lists supported languages, package managers, or ecosystems.
- Example:
Ruby
- Example: