Update frontmatter versions (#54542)
This commit is contained in:
Rachael Sewell
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: About contributing to GitHub Docs
|
||||
shortTitle: About contributing
|
||||
intro: 'You can contribute to GitHub Docs content in several ways.'
|
||||
intro: You can contribute to GitHub Docs content in several ways.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
{% data variables.product.prodname_dotcom %} documentation is open source. Anyone can contribute to the docs in the public `docs` repository: https://github.com/github/docs. {% data variables.product.prodname_dotcom %} employees work on the documentation in a copy of this repository called `docs-internal`. The two repositories are automatically synced to keep them both up to date with changes merged into the `main` branch of either repository. For simplicity, we'll refer to "the documentation repository" in the articles about contributing to {% data variables.product.prodname_docs %}.
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Label reference
|
||||
intro: "Labels can help you find an issue you'd like to help with."
|
||||
intro: Labels can help you find an issue you'd like to help with.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
You can use labels to locate a particular type of issue. For example, click the labels in the table to see a filtered list of open issues in the github/docs repository.
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Using Git on GitHub Docs
|
||||
shortTitle: Using Git
|
||||
intro: 'You can use Git on the command line to commit changes and then push them to the documentation repository.'
|
||||
intro: You can use Git on the command line to commit changes and then push them to the documentation repository.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
This article describes the process of creating a topic branch for the documentation repository, committing changes, and pushing your changes back up to the remote repository.
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Using the content linter
|
||||
intro: 'You can use content linter to check your contributions for errors.'
|
||||
intro: You can use content linter to check your contributions for errors.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About the {% data variables.product.prodname_docs %} content linter
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Using the TODOCS placeholder to leave notes
|
||||
shortTitle: Using the TODOCS placeholder
|
||||
intro: 'You can use the `TODOCS` placeholder to indicate work that still needs to be completed.'
|
||||
intro: You can use the `TODOCS` placeholder to indicate work that still needs to be completed.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
<!-- markdownlint-disable search-replace -->
|
||||
|
||||
@@ -3,7 +3,9 @@ title: Creating a local environment
|
||||
shortTitle: Create a local environment
|
||||
intro: 'You can run the {% data variables.product.prodname_docs %} application locally on your computer.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About {% data variables.product.prodname_docs %} site structure
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Troubleshooting your environment
|
||||
intro: "Learn about troubleshooting problems in your local environment and the {% data variables.product.prodname_docs %} staging platform."
|
||||
intro: 'Learn about troubleshooting problems in your local environment and the {% data variables.product.prodname_docs %} staging platform.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## Troubleshooting tests that fail locally but pass in CI
|
||||
|
||||
@@ -3,7 +3,9 @@ title: Working on GitHub Docs in a codespace
|
||||
shortTitle: Working in a codespace
|
||||
intro: 'You can use {% data variables.product.prodname_github_codespaces %} to work on documentation for {% data variables.product.prodname_docs %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About {% data variables.product.prodname_github_codespaces %}
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: About combining multiple content types
|
||||
shortTitle: Combining multiple types
|
||||
intro: 'You can combine multiple content types in a single article to help people complete complex tasks.'
|
||||
intro: You can combine multiple content types in a single article to help people complete complex tasks.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Often, it's helpful to group information in context to help people complete a complex task, understand a set of related tasks, or illustrate an entire workflow. Use longer articles combining content types to ensure people find contextual content in the right place. Longer articles also help eliminate duplication of content and prepare content to scale as more options are added to the product. People most often need longer articles while actively using the product, and they may need to consult the article at different points on their journey.
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
---
|
||||
title: About the content model
|
||||
shortTitle: About the content model
|
||||
intro: 'The content model describes the structure and types of content that we publish.'
|
||||
intro: The content model describes the structure and types of content that we publish.
|
||||
redirect_from:
|
||||
- /contributing/writing-for-github-docs/content-model
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Our content model explains the purpose of each type of content we create within {% data variables.product.prodname_docs %}, and what to include when you write or update an article. We use a content model to ensure that our content consistently, clearly, and comprehensively communicates the information that people need to achieve their goals with {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: About topics
|
||||
shortTitle: About topics
|
||||
intro: 'Use topics to make articles searchable.'
|
||||
intro: Use topics to make articles searchable.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Conceptual content type
|
||||
intro: 'People most often use conceptual content when they are learning about something new to them.'
|
||||
intro: People most often use conceptual content when they are learning about something new to them.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples.
|
||||
|
||||
@@ -3,7 +3,9 @@ title: Contents of a GitHub Docs article
|
||||
shortTitle: Contents of an article
|
||||
intro: 'Every article includes a few standard elements, and may include conditional or optional elements. We also use a standard order for content within an article.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About the structure of an article
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Procedural content type
|
||||
intro: 'Procedural content gives context on how a task fits into someone''s larger goal.'
|
||||
intro: Procedural content gives context on how a task fits into someone's larger goal.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Procedural content helps people complete a task from start to finish while they are using {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Quickstart content type
|
||||
intro: 'Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.'
|
||||
intro: Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Quickstarts enable people to quickly complete a discrete, focused task by illustrating a workflow with only essential steps, in about five minutes or 600 words. Quickstarts can be used for quickly getting set up with a new tool, or for quickly completing another task. For more complex tasks, use a tutorial.
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Referential content type
|
||||
intro: 'Referential content provides detailed information that people need while they are actively using a feature.'
|
||||
intro: Referential content provides detailed information that people need while they are actively using a feature.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
We create referential articles and referential sections within other articles.
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
title: Release note content type
|
||||
intro: 'Release notes enable readers to understand and prepare for the user-facing changes in each release of {% data variables.product.prodname_dotcom %}''s versioned enterprise products.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Good release notes provide administrators the necessary information to plan system upgrades in environments that require change control, and support end users who want to understand and prepare to use new {% data variables.product.prodname_dotcom %} features and functionality.
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
title: Style guide
|
||||
intro: 'Follow this guide to make sure {% data variables.product.company_short %}''s documentation stays consistent and follows clear patterns that our readers can understand.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/writing-for-github-docs/style-guide
|
||||
---
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
title: Troubleshooting content type
|
||||
intro: 'Troubleshooting content includes built-in errors we expect people to encounter, common problems reported to support, and situations people might encounter while completing tasks.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Use troubleshooting sections in guides or procedural articles to keep solutions close to procedures. Work with support and product managers to surface common errors and include them in the documentation.
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Tutorial content type
|
||||
intro: 'Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem'
|
||||
intro: Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
Tutorials help people learn about products and solve real world problems by guiding them through the entire workflow to complete a task. Tutorials are more conversational in tone than other content. A tutorial feels like a developer-to-developer conversation while remaining accessible to readers with varied technical knowledge. Products with tutorials must already have a quickstart. For bite-sized workflows, use the quickstart model instead.
|
||||
|
||||
@@ -3,7 +3,9 @@ title: About GitHub's documentation fundamentals
|
||||
shortTitle: Documentation fundamentals
|
||||
intro: 'All content published on {% data variables.product.prodname_docs %} must meet these fundamental requirements.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About {% data variables.product.github %}'s documentation fundamentals
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: About GitHub's documentation philosophy
|
||||
shortTitle: Documentation philosophy
|
||||
intro: 'Our documentation philosophy guides what content we create and how we create it.'
|
||||
intro: Our documentation philosophy guides what content we create and how we create it.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About the {% data variables.product.prodname_dotcom %} documentation philosophy
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Annotating code examples
|
||||
shortTitle: Annotate code examples
|
||||
intro: "You can annotate longer code examples to explain how they work and how people can customize them for other uses."
|
||||
intro: You can annotate longer code examples to explain how they work and how people can customize them for other uses.
|
||||
layout: inline
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/annotating-code-examples
|
||||
---
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Best practices for GitHub Docs
|
||||
shortTitle: Best practices for GitHub Docs
|
||||
intro: "Follow these best practices to create documentation that's user-friendly and easy to understand."
|
||||
intro: Follow these best practices to create documentation that's user-friendly and easy to understand.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About {% data variables.product.prodname_dotcom %} documentation
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Changing an article's title
|
||||
shortTitle: Change an article's title
|
||||
intro: "When it's necessary to change the title of an article, the name may need to be updated in several places."
|
||||
intro: 'When it''s necessary to change the title of an article, the name may need to be updated in several places.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/changing-an-articles-title
|
||||
---
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Configuring redirects
|
||||
shortTitle: Configure redirects
|
||||
intro: "If an article's title, version, or location changes, you can create a redirect to the current content."
|
||||
intro: 'If an article''s title, version, or location changes, you can create a redirect to the current content.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/configuring-redirects
|
||||
---
|
||||
|
||||
@@ -3,7 +3,9 @@ title: Content design principles
|
||||
shortTitle: Content design principles
|
||||
intro: 'We share these principles to design and create the best content for people who use {% data variables.product.prodname_dotcom %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About {% data variables.product.prodname_dotcom %}'s content design principles
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Creating diagrams for {% data variables.product.prodname_docs %}
|
||||
title: 'Creating diagrams for {% data variables.product.prodname_docs %}'
|
||||
shortTitle: Create diagrams
|
||||
intro: 'This guide explains when and how to create diagrams for {% data variables.product.prodname_docs %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
allowTitleToDifferFromFilename: true
|
||||
---
|
||||
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Creating reusable content
|
||||
shortTitle: Create reusable content
|
||||
intro: 'You can create reusable content that can be referenced in multiple content files.'
|
||||
intro: You can create reusable content that can be referenced in multiple content files.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About reusables
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Creating screenshots
|
||||
shortTitle: Create screenshots
|
||||
intro: "You can help users locate elements of the user interface that are difficult to find by adding screenshots to {% data variables.product.prodname_docs %}."
|
||||
intro: 'You can help users locate elements of the user interface that are difficult to find by adding screenshots to {% data variables.product.prodname_docs %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About screenshots in {% data variables.product.prodname_docs %}
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Creating tool switchers in articles
|
||||
shortTitle: Create tool switchers
|
||||
intro: 'You can use a tool switcher to show how to complete tasks using specific tools.'
|
||||
intro: You can use a tool switcher to show how to complete tasks using specific tools.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles
|
||||
---
|
||||
|
||||
@@ -3,7 +3,9 @@ title: Making content findable in search
|
||||
shortTitle: Make content findable
|
||||
intro: 'Follow these SEO best practices to help users find {% data variables.product.company_short %} documentation using search engines.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About search engine optimization (SEO)
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
title: Templates
|
||||
intro: 'This article contains starter templates for the different content types used in {% data variables.product.prodname_docs %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## Conceptual article template
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Using Markdown and Liquid in GitHub Docs
|
||||
shortTitle: Markdown and Liquid # Max 31 characters
|
||||
shortTitle: Markdown and Liquid
|
||||
intro: 'You can use Markdown and Liquid to format content, create reusable content, and write content for different versions on {% data variables.product.prodname_docs %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs
|
||||
---
|
||||
|
||||
@@ -3,7 +3,9 @@ title: Using videos in GitHub Docs
|
||||
shortTitle: Use videos
|
||||
intro: 'This guide explains how to create videos that support user needs for {% data variables.product.prodname_docs %}.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About videos in {% data variables.product.prodname_docs %}
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Using YAML frontmatter
|
||||
shortTitle: YAML frontmatter # Max 31 characters
|
||||
shortTitle: YAML frontmatter
|
||||
intro: 'You can use YAML frontmatter to define versioning, add metadata, and control the layout for articles.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter
|
||||
---
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
title: Versioning documentation
|
||||
intro: '{% data variables.product.prodname_docs %} uses YAML frontmatter and liquid operators to support multiple versions of {% data variables.product.company_short %} with a single-source approach.'
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
redirect_from:
|
||||
- /contributing/syntax-and-versioning-for-github-docs/versioning-documentation
|
||||
---
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Writing content to be translated
|
||||
shortTitle: Write content to be translated
|
||||
intro: 'Our documentation is translated into multiple languages. How we approach writing the English language documentation can greatly improve the quality of those translations.'
|
||||
intro: Our documentation is translated into multiple languages. How we approach writing the English language documentation can greatly improve the quality of those translations.
|
||||
versions:
|
||||
feature: 'contributing'
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
---
|
||||
|
||||
## About writing content that is translation-friendly
|
||||
|
||||
Reference in New Issue
Block a user