How we docs megabranch (#36788)

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: hubwriter <hubwriter@github.com>
Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com>
Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
Co-authored-by: Robert Sese <734194+rsese@users.noreply.github.com>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
Co-authored-by: Peter Bengtsson <peterbe@github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>

content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md

@@ -0,0 +1,80 @@
+---
+title: About contributing to GitHub Docs
+shortTitle: About contributing
+intro: 'You can contribute to GitHub Docs content in several ways.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+{% 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 %}.
+
+The documentation repository is the place to discuss and collaborate on the documentation that is published here on [docs.github.com](/).
+
+{% ifversion discussions %}
+
+## Discussions
+
+[Discussions](/discussions/quickstart) are where we have conversations.
+
+If you'd like help troubleshooting a documentation issue or pull request you're working on, have a great new idea for documentation, or want to share something amazing you've learned in our docs, join us in the [`docs` repository discussions](https://github.com/github/docs/discussions).
+
+{% note %}
+
+**Note**: To preserve the bandwidth of the Docs team, off-topic conversations will be closed.
+
+{% endnote %}
+
+{% endif %}
+
+## Issues
+
+[Issues](/github/managing-your-work-on-github/about-issues) are used to track tasks that contributors can help with. If an issue has a `triage` label, we haven't reviewed it yet, and you shouldn't begin work on it.
+
+If you've found something in the documentation content, or something about the docs.github.com website, that should be updated, search the open issues to see if someone else has reported the same thing. If it's something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you'd like to be fixed.
+
+{% note %}
+
+**Note**: {% data variables.product.prodname_dotcom %} employees should open issues in the private `docs-content` repository.
+
+{% endnote %}
+
+## Pull requests
+
+A [pull request](/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository. When we merge those changes, they're deployed to the live site within 24 hours.
+
+We cannot accept contributions to the [REST API reference documentation](/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [`rest-api-description`](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository.
+
+### Reviewing your own pull requests
+
+You should always review your own pull request first, before marking it as ready for review by others.
+
+For content changes, make sure that you:
+
+- Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).
+- Review the content for technical accuracy.
+- Check your changes for grammar, spelling, and adherence to the [style guide](https://github.com/github/docs/blob/main/contributing/content-style-guide.md).
+- Make sure the text in your pull request will be easy to translate. For more information, see "[Translations guide for writers](https://github.com/github/docs/blob/main/contributing/translations-for-writers.md)."
+- Check new or updated Liquid statements to confirm that versioning is correct. For more information, see "[Liquid helpers](https://github.com/github/docs/blob/main/contributing/liquid-helpers.md)."
+- Check the preview of any pages you have changed. A preview is automatically generated after you submit a pull request and links are added to the pull request. The preview sometimes takes several minutes before it is ready to view. Confirm that everything is rendering as expected. Checking the preview will help you identify problems such as typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Make sure to check the rendered output for lists and tables, which can sometimes have problems that are difficult to identify in the Markdown.
+- If there are any failing checks in your pull request, troubleshoot them until they're all passing.
+
+## Support
+
+We are a small team working hard to keep up with the documentation demands of a continuously changing product. Unfortunately, we just can't help with support questions in this repository. If you are experiencing a problem with {% data variables.product.prodname_dotcom %}, unrelated to our documentation, please [contact {% data variables.product.prodname_dotcom %} Support directly](https://support.github.com/contact). Any issues{% ifversion discussions %}, discussions,{% endif %} or pull requests opened in the documentation repository requesting support will be given information about how to contact {% data variables.product.prodname_dotcom %} Support, then closed and locked.
+
+If you're having trouble with your {% data variables.product.prodname_dotcom %} account, contact [Support](https://support.github.com/contact?tags=docs-contributing-guide).
+
+## Translations
+
+This website is internationalized and available in multiple languages. The source content in this repository is written in English. We automate translations through an internal process, working with professional translators to localize the English content.
+
+If you spot a translation error, please raise an issue with the details.
+
+We do not currently accept pull requests for translated content.
+
+## Site policy
+
+{% data variables.product.prodname_dotcom %}'s site policies are also published on docs.github.com.
+
+If you find a typo in the site policy section, you can open a pull request to fix it. For anything else, see "[Contributing](https://github.com/github/site-policy/blob/main/CONTRIBUTING.md)" in the `site-policy` repository.

content/contributing/collaborating-on-github-docs/index.md

@@ -0,0 +1,13 @@
+---
+title: Collaborating on GitHub Docs
+shortTitle: Collaborate on GitHub Docs
+intro: 'Find out about collaborating on GitHub Docs.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /about-contributing-to-github-docs
+  - /using-git-on-github-docs
+  - /using-the-todocs-placeholder-to-leave-notes
+  - /label-reference
+---

content/contributing/collaborating-on-github-docs/label-reference.md

@@ -0,0 +1,17 @@
+---
+title: Label reference
+intro: "Labels can help you find an issue you'd like to help with."
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+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.
+
+| Label | Description |
+| --- | --- |
+| [`help wanted`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Problems or updates that anyone in the community can start working on. | 
+| [`good first issue`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Problems or updates we think are ideal for beginners. | 
+| [`content`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) | Problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown. | 
+| [`engineering`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) | Problems or updates involving the functionality of the docs.github.com website. Fixing these issues will usually require some knowledge of JavaScript/Node.js or YAML. | 
+| [`codespaces`](https://github.com/github/docs/labels/codespaces)<br> [`desktop`](https://github.com/github/docs/labels/desktop)<br> [`graphql`](https://github.com/github/docs/labels/graphql) | Labels for filtering issues by a product or documentation area. | 

content/contributing/collaborating-on-github-docs/using-git-on-github-docs.md

@@ -0,0 +1,205 @@
+---
+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.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+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.
+
+The article assumes you have already cloned the documentation repository locally and you will be making changes on your local computer rather than on {% data variables.product.prodname_dotcom_the_website %} or in a codespace. For more information, see "[AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui)."
+
+## Setting up your topic branch and making changes
+
+To keep your local branches in sync with their remotes and avoid merge conflicts, follow these steps as you work on documentation.
+
+1. In the terminal, change the current working directory to the location where you cloned the documentation repository. For example:
+
+   ```
+   cd ~/my-cloned-repos/docs
+   ```
+
+1. Switch to the default branch: `main`.
+
+   ```
+   git checkout main
+   ```
+
+1. Get the most recent commits from the remote repository.
+
+   ```
+   git pull origin main
+   ```
+
+1. Switch to or create a topic branch.
+   - To start a new project, create a new topic branch from `main`.
+
+     ```
+     git checkout -b YOUR-TOPIC-BRANCH
+     ```
+
+     {% note %}
+
+     **Note**: You can use forward slashes as part of the branch name, for example to include your user name:
+
+     ```
+     git checkout -b my-username/new-codespace-policy
+     ```     
+
+     {% endnote %}
+
+   - To work on an existing project, switch to your topic branch and merge changes from `main`.
+
+     ```
+     git checkout YOUR-TOPIC-BRANCH
+     git merge main
+     ```
+
+     If you run into merge conflicts, follow the steps later in this article for [resolving merge conflicts](#resolving-merge-conflicts).
+
+1. Open your preferred text editor, edit files as required, then save your changes.
+
+## Committing and pushing your changes
+
+1. When you're ready to commit your changes, open a terminal and check the status of your topic branch with `git status`. Make sure you see the correct set of changes.
+
+   ```
+   git status
+   On branch YOUR-TOPIC-BRANCH
+
+   Changes not staged for commit:
+     (use "git add <file>..." to update what will be committed)
+     (use "git checkout -- <file>..." to discard changes in working directory)
+           deleted:    example-deleted-file.md
+           modified:   example-changed-file.md
+
+   Untracked files:
+     (use "git add <file>..." to include in what will be committed)
+           example-new-file.md
+   ```
+
+1. Stage the changed files so that they're ready to be committed to your topic branch.
+
+   - If you created new files or updated existing files, use `git add FILENAME [FILENAME...]`. For example:
+
+     ```
+     git add example-new-file.md example-changed-file.md
+     ```
+
+     This adds the updated version of the files to Git's staging area, from which changes can be committed. To unstage a file, use `git reset HEAD FILENAME`. For example, `git reset HEAD example-changed-file.md`.
+
+   - If you deleted files, use `git rm FILENAME [FILENAME...]`. For example:
+
+     ```
+     git rm example-deleted-file.md
+     ```
+
+1. Commit your changes.
+
+   ```
+   git commit -m "Commit message title (max 72 characters)
+   
+   Optional fuller description of what changed (no character limit). 
+   Note the empty line between the title and the description, 
+   and the closing quotation mark at the end of the commit message."
+   ```
+
+   This commits the staged changes locally. You can now push this commit, and any other unpushed commits, to the remote repository.  
+   
+   To remove this commit, use `git reset --soft HEAD~1`. After running this command our changes are no longer committed but the changed files remain in the staging area. You can make further changes and then `add` and `commit` again.
+
+1. Push your changes to the remote repository on {% data variables.product.prodname_dotcom_the_website %}.
+
+   - The first time you push your branch you can choose to add an upstream tracking branch. This allows you to use `git pull` and `git push` on that branch without additional arguments.
+
+     ```
+     git push --set-upstream origin YOUR-TOPIC-BRANCH
+     ```
+
+   - If you've pushed this branch before, and set an upstream tracking branch you can use:
+
+     ```
+     git push
+     ```
+
+### Best practices for commits
+
+- Favor commits that contain small, focused groups of changes over commits with large, unfocused groups of changes, since this will help you write commit messages that other people can easily understand. An exception is the initial commit for a new project or category. These commits are sometimes large, as they often introduce the bare versions of many articles at once to provide an organizational scheme for subsequent work.
+- If you are incorporating feedback or want to address a set of changes to a particular person or team for review, @mention the person whose suggestions you are incorporating. For example: "Incorporating feedback from @octocat," or "Updating billing configuration steps - cc @monalisa for accuracy."
+- If a commit addresses an issue, you can reference the issue number in the commit, and a link to the commit will appear in the issue conversation timeline: "Addresses #1234 - adds steps for backing up the VM before upgrading." 
+  {% note %}
+
+  **Note**: We generally don't close an issue via a commit. To close an issue, open a pull request and add "Closes #1234" to the description. The linked issue will be closed when the pull request is merged. For more information, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)."
+
+  {% endnote %}
+- Make commit messages clear, detailed, and imperative. For example: "Adds a conceptual article about 2FA," not "Add info."
+- Try not to leave uncommitted changes in your local branch when you finish working for the day. Get to a good stopping point and commit and push your changes so your work is backed up to the remote repository.
+- Only push up to {% data variables.product.prodname_dotcom_the_website %} after you've made a few commits. Pushing after every commit adds noise to our ops channels on Slack and causes unnecessary builds to run.
+
+## Resolving merge conflicts
+
+When you try to merge two branches that contain different changes to the same part of a file, you will get a merge conflict. In our workflow, this most often occurs when merging `main` down into a local topic branch.
+
+There are two ways to handle merge conflicts:
+- Edit the file in your text editor and choose which changes to keep. Then commit the updated file to your topic branch from the command line.
+- [Resolve the merge conflicts on {% data variables.product.prodname_dotcom_the_website %}](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github).
+
+### Resolving merge conflicts by editing the file and committing the changes
+
+1. On the command line, note the files that contains merge conflicts.
+1. Open the first of these files in your text editor.
+1. In the file, look for the merge conflict markers.
+
+   ```
+   <<<<<<< HEAD
+   Here are the changes you've made.
+   =====================
+   Here are the changes from the main branch.
+   >>>>>>> main
+   ```
+
+1. Decide which changes to keep and delete the unwanted changes and the merge conflict markers. If you need to make further changes, you can do so at the same time. For example, you could change the five lines shown in the previous code sample to the single line:
+
+   ```
+   Here are the changes you want to use.
+   ```
+
+   If there are multiple files with merge conflicts, repeat the previous steps until you resolve all conflicts.
+
+   {% note %}
+
+   **Note**: You should apply care when resolving merge conflicts. Sometimes you will simply accept your own changes, sometimes you will use the upstream changes from the `main` branch, and sometimes you will combine both sets of changes. If you're unsure of the best resolution, be wary of replacing the changes from upstream as these may have been made for specific reasons that you're not aware of.
+
+   {% endnote %}
+
+1. In the terminal, stage the file, or files, that you just modified.
+
+   ```
+   git add changed-file-1.md changed-file-2.md
+   ```
+
+1. Commit the files.
+
+   ```
+   git commit -m "Resolves merge conflicts"
+   ```
+
+1. Push the committed changes to the remote repository on {% data variables.product.prodname_dotcom_the_website %}.
+
+   ```
+   git push
+   ```
+
+## Creating a pull request
+
+We recommend you open your pull request on {% data variables.product.prodname_dotcom %} early. Create the pull request as a draft until you are ready for it to be reviewed. Each time you push changes, your commits will be added to the pull request.
+
+{% note %}
+
+**Note**: You can quickly access pull requests you've created by clicking **Pull requests** at the top of every page on {% data variables.product.prodname_dotcom_the_website %}.
+
+{% endnote %}
+
+For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui#creating-the-pull-request)."

content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md

@@ -0,0 +1,30 @@
+---
+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.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## Using the TODOCS placeholder
+
+Sometimes technical writers use placeholders while writing documentation to remind themselves to come back to something later. It's a useful technique, but there's always the possibility that the placeholder will be overlooked and slip into production. At that point, the only way the Docs team will find out about it is if someone sees it and reports it.
+
+To prevent slips, use the string `TODOCS` as your placeholder. The Docs test suite includes a [linting test](https://github.com/github/docs/tree/main/src/content-linter) that will fail if it finds this string anywhere in a Markdown or YAML file.
+
+{% note %}
+
+**Note**: If you use {% data variables.product.prodname_vscode_shortname %} as your text editor, the "[TODO Highlight](https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight)" extension is useful for highlighting instances of "TODOCS" in your files. Add "TODOCS" and other varieties of casing, such as "todocs," to the settings for this extension.
+
+{% endnote %}
+
+### Example
+
+```
+1. In the dropdown, select the settings you want to sync.
+
+   TODOCS: ADD A SCREENSHOT OF THE SETTINGS SYNC OPTIONS
+
+1. Click **Sign in & Turn on**, then select the account to which you want your settings to be synced.
+```

content/contributing/index.md

@@ -0,0 +1,14 @@
+---
+title: Contributing to GitHub Docs
+shortTitle: Contribute to GitHub Docs
+intro: 'Learn about how the {% data variables.product.prodname_docs %} team creates documentation and how you can contribute.'
+layout: product-landing
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /writing-for-github-docs
+  - /syntax-and-versioning-for-github-docs
+  - /collaborating-on-github-docs
+  - /setting-up-your-environment-to-work-on-github-docs
+---

content/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment.md

@@ -0,0 +1,100 @@
+---
+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.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About {% data variables.product.prodname_docs %} site structure
+
+The {% data variables.product.prodname_docs %} site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by [Jekyll](https://jekyllrb.com/). A few years after that it was migrated to [Nanoc](https://nanoc.app/), another Ruby static site generator.
+
+Today it's a dynamic Node.js webserver powered by Express, using [middleware](https://github.com/github/docs/blob/main/middleware/README.md) to support proper HTTP redirects, language header detection, and dynamic content generation to support the various flavors of {% data variables.product.company_short %}'s product documentation, like {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_ghe_server %}.
+
+The tooling for this site has changed over the years, but many of the tried-and-true authoring conventions of the original Jekyll site have been preserved.
+
+- Content is written in Markdown files, which live in the `content` directory.
+<!-- - Content can use the [Liquid templating language](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-for-github-docs).-->
+- Files in the `data` directory are available to templates via the {% raw %}`{% data %}`{% endraw %} tag.
+- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter).
+- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported.
+
+## Setting up your local environment
+
+You can clone the {% data variables.product.prodname_docs %} repository and run the application locally on your computer, after some initial setup.
+
+### Installing Node.js
+
+The {% data variables.product.prodname_docs %} site is powered by Node.js. It runs on macOS, Windows, and Linux environments.
+
+To run the site, you'll need Node.js. To install Node.js, [download the "LTS" installer from nodejs.org](https://nodejs.org). To check which Node version you need, you can see the `package.json` file in the {% data variables.product.prodname_docs %} repository. The Node version is listed in the `engine` field, similar to the following example, which indicates you can use Node major version 16 or Node major version 18.
+
+```json
+"engines": {
+    "node": "^16 || ^18"
+}
+```
+
+If you're using `nodenv`, see the [`nodenv` docs](https://github.com/nodenv/nodenv#readme) for instructions on switching Node.js versions.
+
+### Starting a local {% data variables.product.prodname_docs %} server
+
+Once you've installed Node.js (which includes the popular `npm` package manager), open your terminal and run the following commands.
+
+```sh
+git clone https://github.com/github/docs
+cd docs
+npm ci
+npm run build
+npm start
+```
+
+You should now have a running server. To access your local preview environment, visit [localhost:4000](http://localhost:4000) in your browser.
+
+When you're ready to stop your local server, type <kbd>Ctrl</kbd>+<kbd>C</kbd> in your terminal window.
+
+{% note %}
+
+**Note:** You should typically only need to run `npm ci` and `npm run build` each time you pull the latest version of a branch.
+ - `npm ci` does a clean install of dependencies, without updating the `package-lock.json` file.
+ - `npm run build` creates static assets, such as JavaScript and CSS files.
+
+{% endnote %}
+
+If you would like to read more about debugging and troubleshooting the {% data variables.product.prodname_docs %} application, see "[Troubleshooting](https://github.com/github/docs/blob/main/contributing/troubleshooting.md)" in the github/docs repository.
+
+### Using browser shortcuts
+
+The [`script/bookmarklets`](https://github.com/github/docs/tree/main/script/bookmarklets) directory in the {% data variables.product.prodname_docs %} repository contains browser shortcuts that can help with reviewing {% data variables.product.company_short %} documentation. For more information, see the directory's [`README`](https://github.com/github/docs/tree/main/script/bookmarklets/README.md).
+
+### Enabling different languages
+
+By default, the local server does not run with all supported languages enabled.  If you need to run a local server with a particular language, you can temporarily edit the `start` script in `package.json` and update the `ENABLED_LANGUAGES` variable.  
+
+For example, to enable Japanese and Portuguese in addition to English, you can edit `package.json` and set `ENABLED_LANGUAGES='en,ja,pt'` in the `start` script. Then restart the server for the change to take effect. 
+
+{% note %}
+
+**Note:** Before you commit your changes, you should revert the `package.json` file to its original state.
+
+{% endnote %}
+
+The supported language codes are defined in [`lib/languages.js`](https://github.com/github/docs/blob/main/lib/languages.js).
+
+## Using {% data variables.product.prodname_github_codespaces %}
+
+As an alternative to running {% data variables.product.prodname_docs %} locally, you can use {% data variables.product.prodname_github_codespaces %}. {% data variables.product.prodname_github_codespaces %} enable you to edit, preview, and test your changes directly from your browser. 
+
+For more information about using a codespace for working on {% data variables.product.company_short %} documentation, see "[AUTOTITLE](/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace)."
+
+## Further reading
+
+- [AUTOTITLE](/contributing/writing-for-github-docs/creating-reusable-content)
+- [Components](https://github.com/github/docs/blob/main/components/README.md)
+- [Data](https://github.com/github/docs/blob/main/data/README.md)
+- [Middleware](https://github.com/github/docs/blob/main/middleware/README.md)
+- [Scripts](https://github.com/github/docs/blob/main/script/README.md)
+- [Styles](https://github.com/github/docs/blob/main/stylesheets/README.md)
+- [Tests](https://github.com/github/docs/blob/main/tests/README.md) 

content/contributing/setting-up-your-environment-to-work-on-github-docs/index.md

@@ -0,0 +1,11 @@
+---
+title: Setting up your environment to work on {% data variables.product.prodname_docs %}
+shortTitle: Your working environment
+intro: 'Learn about running the {% data variables.product.prodname_docs %} site locally or in {% data variables.product.prodname_github_codespaces %}.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /working-on-github-docs-in-a-codespace
+  - /creating-a-local-environment
+---

content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md

@@ -0,0 +1,44 @@
+---
+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 %}.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About {% data variables.product.prodname_github_codespaces %} 
+
+{% data variables.product.prodname_github_codespaces %} allows you to work in a development environment that's hosted remotely from your machine. You can get started quickly, without needing to set up the working environment or download files to your local computer.
+
+For more information, see "[AUTOTITLE](/free-pro-team@latest/codespaces/overview)."
+
+## Working on documentation in a codespace
+
+The following steps assume you have {% data variables.product.prodname_github_codespaces %} set up to edit files using {% data variables.product.prodname_vscode %} for Web. The steps are very similar if you have set a different editor. For more information, see "[AUTOTITLE](/free-pro-team@latest/codespaces/customizing-your-codespace/setting-your-default-editor-for-codespaces)."
+
+1. Navigate to the open source repository for {% data variables.product.prodname_docs %},  [`github/docs`](https://github.com/github/docs).
+1. If you're an open source contributor, create a fork of the repository, then follow the rest of the steps in this procedure from your fork. For more information, see "[AUTOTITLE](/get-started/quickstart/fork-a-repo)."
+1. Create a branch to work on. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)."
+1. On the main page of the repository, click **{% octicon "code" aria-hidden="true" %} Code**, then click **Create codespace on BRANCH-NAME**.
+   
+   The "Setting up your codespace" page is displayed. After a short time the browser-based version of {% data variables.product.prodname_vscode %} is displayed.
+1. Use the Explorer to navigate to the markdown file you want to edit. If the file is an article, it will be located in the `content` directory. If the file is reusable content, it will be located in the `data` directory.
+   
+   In most cases, the path to an article in the `content` directory matches the path in the URL, minus the `.md` file extension. For example, the source for the article `https://docs.github.com/en/codespaces/getting-started/quickstart` is the markdown file `content/codespaces/getting-started/quickstart.md`.
+1. Edit the markdown file as required.
+1. Save your changes.
+1. Commit and push your changes, either using the Source Control view, or using Git commands from the Terminal. For more information, see "[AUTOTITLE](/get-started/using-git/about-git)."
+
+## Creating a pull request
+
+1. Navigate to the "Pull requests" tab of the `github/docs` repository at [github.com/github/docs/pulls](https://github.com/github/docs/pulls).
+1. Click **New pull request**.
+1. If you're an open source contributor, click **compare across forks**, then choose the forked repository you created and your working branch.
+   
+   Otherwise, change the "compare" branch to your working branch.
+1. Check that the changes displayed include all of the changes you made in the codespace. If they do not, this may indicate there are changes you have not pushed from the codespace to {% data variables.product.prodname_dotcom %}.
+1. Click **Create pull request**.
+1. Enter the details for your pull request and click **Create pull request**.
+
+   Your pull request will be reviewed by a member of the {% data variables.product.prodname_docs %} team.

content/contributing/syntax-and-versioning-for-github-docs/changing-an-articles-title.md

@@ -0,0 +1,58 @@
+---
+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."
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+# Changing the title of an article
+
+Sometimes, it's necessary to change the title of a help article. There are several considerations to keep in mind when you retitle an article.
+
+
+## Background on changing the filename
+
+The title of the article corresponds directly to the name of the Markdown file that contains that article, for a couple of reasons:
+
+- **SEO:** When we use real words that correlate to the content of the article in a URL, our articles are weighted more heavily for search engines. For more information, see "Improve the structure of your URLs" in the [Google Search Engine Optimization Starter Guide](http://static.googleusercontent.com/media/www.google.com/en//webmasters/docs/search-engine-optimization-starter-guide.pdf).
+
+## Places you should consider updating when you change a title
+
+There are several places you may need to update when you give an article a new title.
+
+### Frontmatter and metadata section
+
+Each article contains a metadata section or frontmatter located at the **top of the article** formatted using YAML syntax. This metadata section generates the title of the article and contains other important data, such as redirects and sometimes even short description conrefs that link to reusable intro text.
+
+```
+---
+title: Your article name
+intro:
+redirect_from:
+  - /articles/older-outdated-article-name/
+---
+```
+#### Frontmatter update checklist
+
+- Update title using sentence case
+- Update redirects. Almost every time we retitle an article, we should add a redirect referencing the article's old URL and make sure we keep any redirects in the old article's frontmatter.
+ 
+### Filename
+
+You can use the [`git mv` command](https://git-scm.com/docs/git-mv) in your terminal to change the name of the file.
+
+`$ git mv old-article-name.md new-article-name.md`
+
+### Parent index file
+
+Make sure to update the link to the file in its parent `index.md` file, which generates the TOC.
+
+### Inline links within other articles
+
+We link between articles in our documentation. We recommend searching for both the filename *and* title to find links to update.
+
+### Links across {% data variables.product.prodname_dotcom %}
+
+Search in product for links to the old title. If you find any outdated links, contact the relevant team or engineers to let them know the link has changed and ask them to update it. If you're not sure who to contact, you can ask a member of the {% data variables.product.prodname_docs %} team. As a courtesy, you can also create a pull request with the updated links and ask the relevant team to merge it after the updated article title ships.

content/contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles.md

@@ -0,0 +1,42 @@
+---
+title: Creating tool switchers in articles
+shortTitle: Creating tool switchers
+intro: 'You can use a tool switcher to show how to complete tasks using specific tools.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About tool switchers
+
+In some articles, we write content tailored to different tools (the {% data variables.product.prodname_dotcom %} UI, {% data variables.product.prodname_cli %}, {% data variables.product.prodname_desktop %}, cURL, {% data variables.product.prodname_codespaces %}, {% data variables.product.prodname_vscode_shortname %}, GraphQL API, etc.) The tool switcher lets people select a tool to see only the content that is relevant to that tool since tools may have different conceptual or procedural information. People can use the tool switcher in two ways when reading the docs.
+
+**Exploring**
+For tasks that can be completed with different tools, the tool switcher signals to people that there are multiple ways a task can be done. For example, using the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_desktop %}, instead of the {% data variables.product.prodname_dotcom %} UI.
+
+**Getting to the point**
+When someone knows how they want to do a task and doesn’t need to see additional options, the tool switcher removes less relevant content, so they can find exactly what they need.
+
+## Using tool tags
+We use tool tags to divide information for each tool. On rare occasions, we will add new tools.
+
+Tool tags are a key value pair. The key is the tag you use to refer to the tool in the article and the value is how the tool will be identified on the tool picker at the top of the article. The existing tools are in [`lib/all-tools.js`](https://github.com/github/docs/blob/main/lib/all-tools.js) in the {% data variables.product.prodname_docs %} repository.
+
+### When to use tool tags
+We only use tool tags if an article must have tool-specific information to help people accomplish their tasks. If the conceptual information or procedural steps for a task are significantly different depending on what tool someone uses, and we want people to be able to accomplish the task with different tools, we use tool tags to present the relevant information in an article.
+
+Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts described in an article change based on what tool someone uses.
+
+### How to use tool tags
+Tool tags are Liquid tags that wrap content specific to a tool. <!--For more information on using tool tags in an article, see [AUTOTITLE](/contributing/using-markdown-and-liquid-in-github-docs#tool-tags)."-->
+
+Put tools in alphabetical order. By default, the first tool tag will be selected for an article. You can define a different default tool for an article by specifying a `defaultTool:` property in the article's frontmatter. For more information, see the [content README](https://github.com/github/docs/blob/main/content/README.md#defaulttool).
+
+You can also link to an article with a specific tool selected by adding `?tool=TOOLNAME` to the end of the link. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#links-to-a-specific-tool)."
+
+Only include a maximum of eight different tools in an article. Including more tools causes the tool switcher tabs to overflow with an article's table of contents, which prevents people from using either the tool switcher or table of contents. It is unlikely that you will ever need to include eight separate tools in an article. In general, plan to use as few separate tools as possible in an article.
+
+## Adding new tools
+If a writer determines that adding a new tool is the only way to accurately document something, they should explain their reasoning in the content planning stage. Whoever reviews content plan should consider if there are any alternative ways to address the documentation need without adding a new tool. If a new tool is the only way to create accurate documentation, the new tool should be added. If there is an alternative content solution that does not add a new tool, that option should be used.
+
+To add a new tool, add an entry to the `allTools` object in the [`lib/all-tools.js`](https://github.com/github/docs/blob/main/lib/all-tools.js) file as a key-value pair. Add new tools in alphabetical order.

content/contributing/syntax-and-versioning-for-github-docs/index.md

@@ -0,0 +1,11 @@
+---
+title: Syntax and versioning for GitHub Docs
+shortTitle: Syntax and versioning
+intro: 'Learn about using Liquid, YAML, and Markdown to format and version GitHub''s documentation.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /changing-an-articles-title
+  - /creating-tool-switchers-in-articles
+---

content/contributing/writing-for-github-docs/about-githubs-documentation-philosophy.md

@@ -0,0 +1,19 @@
+---
+title: About GitHub's documentation philosophy
+shortTitle: Documentation philosophy
+intro: 'Our documentation philosophy guides what content we create and how we create it.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+# About the {% data variables.product.prodname_dotcom %} documentation philosophy
+
+As the home to the world's largest community of developers, we want to make sure that our documentation is accurate, valuable, inclusive, and easy to use. Our documentation philosophy leads us toward these goals.
+
+- We advocate for our users. This can occur at any point in the documentation process, from planning to writing to publishing. We respond to feedback and proactively work to create the best user experience possible on the {% data variables.product.prodname_docs %} site.
+- We write for an international audience, so that our content can be translated and is inclusive of all people.
+- We create content that can be accessed by a broad group of users. Our content toolkit includes resources and guidance to reduce barriers for people with disabilities and we prioritize keeping up to date with the latest accessibility standards.
+- We create task-based content. We consider what people are trying to accomplish when they use {% data variables.product.prodname_dotcom %}, and then we create content that helps them achieve their goals and discover new possibilities.
+- We collaborate with teams across {% data variables.product.prodname_dotcom %} and the open source community to create high-quality content.
+- We continually learn and improve to curate the best experience for people using {% data variables.product.prodname_dotcom %}.

content/contributing/writing-for-github-docs/content-design-principles.md

@@ -0,0 +1,27 @@
+---
+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 %}.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About {% data variables.product.prodname_dotcom %}'s content design principles
+
+We create product documentation that helps, teaches, and engages everyone who uses {% data variables.product.prodname_dotcom %}. One step of this work is designing the content that we write. We follow these principles when designing and planning content.
+
+- Our content is user-centered and inclusive. We respect everyone who visits the docs and make content that works for them with our strategy, design, and style choices.
+- Our content explains why our products are useful and helps people achieve their goals and priorities.
+- We spend our resources creating high-quality, valuable documentation for {% data variables.product.prodname_dotcom %}’s community.
+- We create just enough docs - more content makes everything more difficult to find, and anything added dilutes everything else ({% data variables.product.prodname_dotcom %} Zen).
+- We iterate and ship to learn - as we learn more from experience, industry expertise, and working with our {% data variables.product.prodname_docs %} community, we adjust our processes, practices, and guidelines.
+
+We provide a style guide and content models as building blocks and guidelines for anyone to design and create documentation.
+
+- Our style guide and content models apply to a range of scenarios.
+- Decisions are based on what is best for people using our docs, not simply what is right or wrong according to grammar or style rules.  We are flexible and open to change while maintaining consistency.
+- We focus our attention on documenting high-impact, high-value scenarios rather than attempting to comprehensively cover every possible use case for the many {% data variables.product.prodname_dotcom %} products and features.
+- Our highest priorities are clarity, meaning, correctness, and consistency.
+- When making a style or structure decision, we consider what people are trying to do with the information and how our content can best support their goals.
+- When a question specific to documentation is not covered by the style guide or content model, we evaluate it using these principles, then make a decision.

content/contributing/writing-for-github-docs/content-model.md

@@ -0,0 +1,576 @@
+---
+title: Using the GitHub Docs content model
+shortTitle: Content model
+intro: 'The content model describes the structure and types of content that we publish.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+allowTitleToDifferFromFilename: true
+---
+
+## About the content model for {% data variables.product.prodname_docs %}
+
+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 %}.
+
+We use these types across all documentation sets to provide a consistent user experience––any content type applies to any product or audience. Our content types evolve over time and we add new types as needed. We only publish content that follows the model.
+
+Consistency helps people form mental models of the documentation and understand how to find the information they need as they return to {% data variables.product.prodname_docs %} over time. It is also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you are an open source contributor making your first commit or a writer on the {% data variables.product.prodname_dotcom %} staff documenting an entire new product.
+
+## Content structure
+
+Docs are organized into multiple levels of hierarchy on our site.
+
+- Top-level doc set
+  - Categories
+    - Map topics
+      - Articles
+
+### Homepage content
+
+The {% data variables.product.prodname_docs %} homepage, [docs.github.com](/), highlights the most important topics that people want to find. We limit the number of doc sets on the homepage so that people can find information and the homepage does not become overcrowded and difficult to search.
+
+The homepage includes all top-level doc sets and some categories. Content on the homepage is organized around {% data variables.product.prodname_dotcom %} concepts and practices. For example, the "CI/CD and DevOps" group includes top-level doc sets for {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, and {% data variables.product.prodname_pages %}.
+
+#### Adding a doc set to the homepage
+
+The goal of the homepage is to help people find information about the {% data variables.product.prodname_dotcom %} feature or product that they want to learn about. Every item added to the homepage dilutes the discoverability of every other item, so we limit the number of doc sets included on the homepage.
+
+If a new top-level doc set is created, it is added to the homepage.
+
+If a category serves as the starting point for using a {% data variables.product.prodname_dotcom %} product or feature, it can be added to the homepage.
+
+For example, under the "Security" grouping on the homepage, in addition to the "[Code security](/code-security)" top-level doc set, the "[Supply chain security](/code-security/supply-chain-security)," "[Security advisories](/code-security/security-advisories)," "[{% data variables.product.prodname_dependabot %}](/code-security/dependabot)," "[{% data variables.product.prodname_code_scanning_caps %}](/code-security/code-scanning)," and "[{% data variables.product.prodname_secret_scanning_caps %}](/code-security/secret-scanning)" categories are included because each of those categories are the entry point to {% data variables.product.prodname_dotcom %} products and features. "[Security overview](/code-security/security-overview)" is not included on the homepage because it provides additional information for using code security products and is not an introduction to a product or feature.
+
+### Top-level doc set
+
+Top-level doc sets are organized around a {% data variables.product.prodname_dotcom %} product, feature, or core workflow. All top-level doc sets appear on the {% data variables.product.prodname_docs %} homepage. You should only create a top-level doc set when there is a large amount of content to be contained in the new doc set, multiple categories that are broken down into map topics, and the topic applies across products, features, or account types. If the content could fit in any existing top-level doc set, it probably belongs in that existing doc set.
+- Top-level doc sets are of roughly equal importance to one another (each is centered on a {% data variables.product.prodname_dotcom %} product or major feature).
+- Most top-level doc sets have a landing page layout, unless there is a significant exception. For example, the "[Site policy](/free-pro-team@latest/site-policy)" doc set does not have guides or procedural articles like other doc sets, so it does not use a landing page layout.
+
+#### Titles for top-level doc sets
+- Feature or product based.
+- Describes what part of {% data variables.product.prodname_dotcom %} someone is using.
+- Examples
+  - [AUTOTITLE](/organizations)
+  - [AUTOTITLE](/issues)
+
+### Category
+
+Categories are organized around a feature or a discrete set of tasks within a top-level doc set aligned with product themes. A category's subject is narrow enough that its contents are manageable and does not grow too large to use. Some categories appear on the homepage.
+- Categories often start small and grow with the product.
+- Large categories may contain map topics to subdivide content around more specific user journeys or tasks.
+- Use long procedural articles to group related chunks of content and keep articles within the category streamlined.
+- When categories have more than ten articles, consider breaking the content into map topics or additional categories.
+
+#### Titles for categories
+- Task-based (begins with a gerund).
+- Describes the big-picture purpose or goal of using the feature or product.
+- General or high-level enough to scale with future product enhancements.
+- Category titles must be 67 characters or shorter and have a [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) less than 27 characters.
+- Examples
+  - [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github)
+  - [AUTOTITLE](/pull-requests/committing-changes-to-your-project)
+  
+#### Intros for categories
+All categories have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. If you significantly change a category’s structure, check its intro for needed updates.
+
+### Map topic
+
+Map topics introduce a section of a category, grouping articles within a category around more specific workflows or subjects that are part of the category’s larger task.
+
+Map topics contain at least three articles. When map topics have more than eight articles, it may be useful to consider breaking the content into more specific map topics.
+
+#### Titles for map topics
+- Task-based (begins with a gerund).
+- Describes a more specific task within the larger workflow of the category it’s in.
+- General or high-level enough to scale with future additions to the product.
+- Map topic titles must be 63 characters or shorter and have a [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) less than 30 characters.
+- Examples
+  - [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain)
+  - [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise)
+
+#### Intros for map topics
+All map topics have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. If you add or remove articles in a map topic, check its intro for needed updates.
+
+### Article
+
+An article is the basic unit of content for {% data variables.product.prodname_docs %}––while we use multiple content types, they are all published as articles. Each content type has its own purpose, format, and structure, yet we use standard elements in every article type, like intros, to ensure articles provide a consistent user experience.
+
+## Content order
+
+We organize content predictably within categories, map topics, and articles. From broadest applicability to most specific, narrow, or advanced information, following this order:
+- Conceptual content
+- Referential content
+- Procedural content for enabling a feature or setting
+- Procedural content on using a feature
+- Procedural content on managing a feature or setting
+- Procedural content on disabling a feature or setting
+- Procedural content on destructive actions (e.g. deletion)
+- Troubleshooting information
+
+### Topics
+
+Topics are used to filter articles and are searchable across the {% data variables.product.prodname_docs %} site. For some layouts, such as landing pages or guides, people can select which articles are displayed by filtering topics. Use these guidelines to help choose which topics to add to an article's frontmatter. For more information on adding topics to an article see, "[Topics](https://github.com/github/docs/tree/main/content#topics)" and for a list of all allowed topics, see [`allowed-topics`](https://github.com/github/docs/blob/main/data/allowed-topics.js).
+
+#### Topics for all content types
+- All articles should have at least one topic
+- 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` or `GraphQL` rather than just `API`
+  - 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 {% data variables.product.prodname_actions %} or the product element called an action
+- 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
+- Use `Fundamentals` for articles related to the core concepts of a product area.
+  - Use: `Fundamentals` in an article like “Introduction to {% data variables.product.prodname_actions %}”
+  - Avoid: `Actions` in an article like "Introduction to {% data variables.product.prodname_actions %}"
+- Commonly-recognized abbreviations can be used, but obscure or ambiguous abbreviations should be avoided
+  - Use: `CI` instead of `Continuous integration`
+  - Avoid: `AS` instead of `Advanced Security`
+- Use the short forms of {% data variables.product.prodname_dotcom %} product names
+  - Use: `Actions` instead of `GitHub Actions`
+
+#### 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`
+- Is the feature part of a restricted program?
+  - Example: `Advanced Security`
+- What element of the feature or product is the article?
+  - Example: `Organizations`
+- What is the broad purpose of the article?
+  - Example: `Permissions`
+- 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`
+
+### Reusing content
+
+We use reusable and variable strings to use the same chunk of content, such as a procedural step or a conceptual paragraph, in multiple places. We generally don't reuse large sections of articles without a specific reason. When an entire section of an article might be relevant in more than one article, take a look at the purpose of both. Is there an opportunity to create a single, long-form article? Refer to the content models to clarify the best permanent home for the information, and link to it from the other article.
+
+## Content types
+
+Any of these content types can be shared as an article on its own or used as sections within a larger article.
+
+### Conceptual
+
+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. People most often use conceptual content when they are learning about something new to them.
+
+We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article.
+
+#### How to write conceptual content
+Use the [conceptual content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#conceptual) to write a conceptual article.
+
+- Describe in plain language what the feature, product, or topic is.
+- Describe its purpose and why it’s useful to the reader.
+- Share use cases or examples.
+- If relevant, describe how the feature or topic works (be mindful of audience and the right location for deep dives into technical details).
+- Highlight any details the reader needs to know to use the feature.
+- Include next steps for getting started with the feature (whether through further reading links or content within the article itself).
+
+#### Titles for conceptual content
+- Conceptual articles or headers of conceptual sections start with "About [subject]”.
+- Use a noun to describe the subject.
+  - Use: "About {% data variables.product.prodname_code_scanning %}"
+  - Avoid: "About scanning your code for vulnerabilities"
+
+#### Examples of conceptual content
+- Conceptual articles
+  - [About GitHub Sponsors](/free-pro-team@latest/sponsors/getting-started-with-github-sponsors/about-github-sponsors)
+  - [About Enterprise accounts](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts)
+- Conceptual sections within other articles
+  - "About security policies" in [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository#about-security-policies)
+  - "About maintenance mode" in [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode#about-maintenance-mode)
+
+### Referential
+
+Referential content provides detailed information that people need while they are actively using a feature.
+
+We create referential articles and referential sections within other articles.
+- Some major subjects may require their own referential article, especially if there is a large amount of referential content, such as for search syntax or YAML syntax in {% data variables.product.prodname_actions %}.
+- For smaller amounts of content or more specific information, like a list of a feature’s supported languages or hardware requirements, use referential sections in context within procedural or conceptual articles.
+
+#### How to write referential content
+Use the [referential content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#referential) to write a referential article.
+
+- Write a sentence or an entire conceptual section to introduce the referential content.
+- Present the actual referential content clearly and consistently.
+- For subjects with a single element to explain, use a list.
+  - Example: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-roles-for-organizations)
+- For subjects with multiple elements to explain, use a table.
+  - Example: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permissions-for-each-role)
+- For longer referential content, such as YAML syntax for workflows, use headers consistently.
+  - H2 headers for each distinct section.
+  - H3 headers for subsections, such as examples.
+  - Example: [AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions)
+
+#### Titles for referential content
+- Referential articles or headers of referential sections clearly describe the contents of the section, and generally begin with nouns.
+- Titles include enough information to be accessible to novice users and fully describe the contents of each section.
+- Titles avoid stacked nouns - use prepositions to break up long strings of nouns.
+
+#### Examples of referential content
+- Referential articles
+  - [AUTOTITLE](/get-started/using-github/keyboard-shortcuts)
+  - [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
+  - [AUTOTITLE](/free-pro-team@latest/rest/reference/billing) in the REST API documentation
+  - [AUTOTITLE](/graphql/reference/mutations) in the GraphQL API documentation
+- Referential sections within other articles
+  - "Supported languages" in [AUTOTITLE](/free-pro-team@latest/get-started/using-github/github-mobile#supported-languages-for-github-mobile)
+  - "Hardware considerations" in [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws#hardware-considerations)
+
+### Procedural
+
+Procedural content helps people complete a task from start to finish while they are using {% data variables.product.prodname_dotcom %}. Procedural content gives context on how the task fits into someone's larger journey.
+
+We create procedural articles and procedural sections within larger articles.
+
+#### How to write procedural articles
+Use the [procedural content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#procedural) to write a procedural article.
+
+- Follow the style guidelines for procedural steps in "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#procedural-steps)".
+- Procedural content can get repetitive––look for opportunities to group related content into a single longer article.
+  - Group multiple related procedures into a single article unless there's a reason not to.
+  - If disabling a setting or undoing a task requires the same steps and has no special implications, do not write a separate procedure.
+  - If disabling a setting or undoing a task requires different steps or has important or special implications, create a longer article to contain both procedures. Use an agnostic title.
+- Tell readers the expected outcome of the procedure.
+- Include troubleshooting tips as frequently as possible.
+
+#### Titles for procedural content
+- Procedural articles or procedural sections within articles are task-based and begin with a gerund.
+  - Use: "Applying for a student developer pack"
+- Use active and specific verbs (brainstorm or use a thesaurus when needed).
+- Titles specifically describe the task contained within the article or header, but are general enough to reflect all of the content.
+- Article title length: maximum 80 characters, 60 if possible.
+
+#### Examples of procedural content
+- [AUTOTITLE](/free-pro-team@latest/billing/managing-your-github-billing-settings/adding-information-to-your-receipts)
+- [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise)
+- [AUTOTITLE](/actions/using-workflows/using-starter-workflows)
+
+### Release notes
+
+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 (e.g., {% data variables.product.prodname_ghe_server %}). 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.
+
+Writers source, edit, and publish release notes in collaboration with product DRIs, feature owners, and individual engineers at {% data variables.product.prodname_dotcom %}. For each individual release, we group release notes by predefined types.
+
+We publish the release notes for [{% data variables.product.prodname_ghe_server %}](/enterprise-server@latest/admin/release-notes)(GHES) and [{% data variables.product.prodname_ghe_managed %}](/github-ae@latest/admin/release-notes)(GHAE) on {% data variables.product.prodname_docs %}, in the "Enterprise administrators" documentation set.
+
+#### Types of releases
+
+{% data variables.product.prodname_docs %} provides release notes for feature releases of GHES and GHAE, and for patch releases of GHES. For more information about releases of each product, see "About upgrades to new releases" in the [GHES](/enterprise-server@latest/admin/overview/about-upgrades-to-new-releases) or [GHAE](/github-ae@latest/admin/overview/about-upgrades-to-new-releases) documentation.
+
+#### Guidance and example release notes
+
+You can find guidance for the format, style, and tone of release notes, as well as examples of each type of note, in "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide)".
+
+### Troubleshooting
+
+Troubleshooting content includes built-in errors we expect people to encounter, common problems reported to support, and situations people might encounter while completing tasks. 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.
+
+#### Known issues
+Known issues are a subset of troubleshooting content specifically designed to respond to bugs, UX/UI issues, and other product quirks that generate a high volume of support tickets. Where troubleshooting content can describe errors that people *might* encounter, known issues explain problems that people *will* encounter.
+
+Like all troubleshooting content, known issues can be a section in an article or a standalone article. If a known issue applies to a specific article, document it in that article. If a known issue applies to a specific set of articles or conceptual grouping of features, or if a product or feature has multiple known issues that should be grouped together, create a dedicated "Known issues with NAME" article.
+
+Known issue content for a product or feature does not need to be comprehensive. Unlike other troubleshooting content, some known issues may not have workarounds. The goal of documenting an issue without a workaround is to help people confirm that the issue exists and save them time searching for a solution that doesn't exist yet after {% data variables.product.prodname_dotcom %} has already determined there isn't a workaround.
+
+Product and feature owners (PMs and EMs) should help plan and review known issue content.
+
+Use known issues to explain the following situations.
+
+- Product behavior that regularly contradicts people's expectations, but is not yet prioritized for remediation.
+- Behavior that regularly prevents the use of the product or feature for a common purpose.
+- Rare or severe bugs that {% data variables.product.prodname_dotcom %} has not yet prioritized fixing, and that are not explained in the product or by existing content on {% data variables.product.prodname_docs %}.
+
+#### How to write troubleshooting content 
+- Use any {% data variables.product.prodname_docs %} content type to create troubleshooting sections.
+- Whenever possible, keep troubleshooting content contained within procedural content or guides.
+- You can create a troubleshooting article when it makes sense to keep it separate, such as when there’s a large amount of troubleshooting content on a particular topic.
+- You can create a troubleshooting map topic if a product or feature has many troubleshooting articles, for example "[AUTOTITLE](/authentication/troubleshooting-ssh)."
+
+#### Title guidelines for troubleshooting content
+- Troubleshooting FEATURE
+- Error: ERROR NAME
+- Known issues for PRODUCT
+
+#### Examples of troubleshooting content
+- "[AUTOTITLE](/authentication/troubleshooting-ssh)"
+- "[AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#troubleshooting-connectivity-through-a-load-balancer)"
+- "[Known issues](/enterprise-server@3.7/admin/release-notes#3.7.8-known-issues)" in the {% data variables.product.prodname_ghe_server %} release notes
+- "[AUTOTITLE](/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit)"
+
+### Combining multiple content types
+
+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.
+
+#### How to combine multiple content types in an article
+- Use conceptual, procedural, referential, troubleshooting, or known issue content in a longer article, and do not use quickstart or tutorials.
+- Use sections of different content types in the article as needed, and follow title guidelines for the content type.
+- Most often, these articles will contain at least one procedural section plus at least one additional conceptual, referential, or procedural section.
+- Use the content ordering guidelines to organize headers within the article.
+- Use troubleshooting information as frequently as possible.
+- You can replicate the article’s title in a header if needed.
+
+#### Title guidelines for articles that combine multiple content types
+- If there is a procedure within the article, use a task-based title that begins with a gerund.
+- Titles are general enough to describe the range of information and tasks contained within the article.
+- Titles describe the setting being toggled and are agnostic about what setting the reader chooses, e.g., "Setting repository visibility” instead of "Making a private repository public.”
+
+#### Examples of articles that combine multiple content types
+- [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility)
+- [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
+- [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-github-account/upgrading-your-github-subscription)
+- [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode)
+
+### Quickstart
+
+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.
+
+Quickstarts are useful when someone already understands the feature or product and is ready to try it out. Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.
+
+#### How to write a quickstart
+Use the [quickstart template](https://github.com/github/docs/blob/main/contributing/content-templates.md#quickstart) to create a quickstart guide.
+
+Contents of quickstarts:
+- Introduction:
+  - Highlights that this guide is quick and to-the-point by using phrasing like:
+      - Quickly add [FEATURE] to your project
+      - The essentials for getting started with [PRODUCT]
+      - An abbreviated guide for people who are familiar with [FEATURE]
+  - Clarifies audience
+  - Clearly states prerequisites and prior knowledge needed
+  - States what someone will accomplish or build
+- Procedural sections
+  - Based on the quickstart's audience, the steps can be less explicit and formal than those used in procedural content. You do not have to use existing reusables to form these steps if the audience doesn’t require that level of detail.
+  - Link out to other articles or resources rather than replicating them, to avoid interrupting the flow of information.
+  - Give visual cues. Use code blocks and screenshots heavily to help reassure people that they are performing the correct actions.
+- Troubleshooting (optional)
+  - If relevant troubleshooting content exists for the quickstart, provide links to it.
+- Next steps
+  - Provide a quick recap of what has been accomplished in the quickstart as a means of transitioning to next steps.
+  - Include 2-3 actionable next steps that someone can take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in {% data variables.product.prodname_learning %}.
+
+#### Title guidelines for quickstarts
+- When the guide helps someone get started with a new tool, preface the title with "Quickstart", e.g. "Quickstart for GitHub Actions" or "Quickstart: Procedural title."
+- For other use cases, follow the title guidelines for procedures and omit the word "Quickstart."
+
+#### Examples of quickstarts
+- [AUTOTITLE](/free-pro-team@latest/actions/quickstart)
+- [AUTOTITLE](/free-pro-team@latest/discussions/quickstart)
+- [Quickstart for GitHub Educators](/free-pro-team@latest/education/quickstart)
+
+### Tutorial
+
+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.
+
+Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem. Tutorials are for people who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help people who've implemented similar solutions in the past with other products use {% data variables.product.prodname_dotcom %}. Tutorials can also help people validate whether the solution is appropriate for their needs.
+
+#### How to write a tutorial
+Use the [tutorial template](https://github.com/github/docs/blob/main/contributing/content-templates.md#tutorial) to create a tutorial.
+
+Contents of tutorials:
+- Introduction
+  - Clarifies audience.
+  - Clearly states prerequisites and prior knowledge needed.
+  - States what someone will accomplish or build.
+  - Includes an example of a successful project.
+  - Does not include the expected amount of time that it may take someone to complete the task - this depends on the experience level of the person completing the tutorial.
+- Procedural sections
+  - Based on the tutorial's audience, the steps can be less explicit and formal than those used in procedural content. You do not have to use existing reusables to form these steps if the audience doesn’t require that level of detail.
+    - Use: "From your profile, click **Settings, and then click **Developer settings**.”
+    - Avoid: In the upper-right corner of any page, click your profile photo, then click **Settings**. In the left sidebar, click **Developer settings**.
+  - Link out to other articles or resources rather than replicating them, to avoid interrupting the flow of information in the tutorial.
+  - Give visual cues. Use code blocks and screenshots heavily to help reassure people that they are performing the correct actions.
+  - Provide real examples.
+    - For example, do not tell someone to "Enter a commit message" - instead, give them an appropriate example commit message that matches the previous steps.
+- Troubleshooting
+  - Acknowledge what may go wrong in the task and list a few common problems readers might run into with solutions.
+- Conclusion
+  - Review what was accomplished or built. Refer back to the project provided in the introduction as an example of a successful project.
+- Next steps
+  - Include 2-3 actionable next steps that someone can take after completing the tutorial. Link off to other related information like:
+    - Projects on {% data variables.product.prodname_dotcom %} that illustrate the introduced concepts
+    - Relevant information on docs.github.com
+    - Relevant {% data variables.product.prodname_learning %}
+    - Relevant published talks, blog posts, or Community Forum series posts by Hubbers
+
+#### Title guidelines for tutorials
+- Follow the title guidelines for procedural articles.
+- Do not use "tutorial” or "guide” in the title.
+
+#### Examples of tutorials
+Tutorials:
+- [AUTOTITLE](/actions/managing-issues-and-pull-requests/adding-labels-to-issues)
+- [AUTOTITLE](/actions/deployment/deploying-xcode-applications/installing-an-apple-certificate-on-macos-runners-for-xcode-development)
+
+Language and framework guides:
+- [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-nodejs)
+- [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-python)
+- [AUTOTITLE](/actions/publishing-packages/publishing-java-packages-with-maven)
+
+### Guides
+
+We collectively refer to tutorials and quickstarts as "guides" across the site. On `/guides` landing pages, we include tutorials, quickstarts, and certain procedural articles in the list of guides for a doc set.
+
+## Contents of a {% data variables.product.prodname_docs %} article
+
+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.
+
+Within an article, there is a standard order of content sections. Every article contains required elements. Articles will also contain conditional elements and optional elements outlined in content design or creation. See the guidelines below for more details.
+
+1. Title
+2. Product callout (conditional)
+3. Intro
+4. Permissions statement (conditional)
+5. Tool switcher (conditional)
+6. Table of contents
+7. Conceptual content
+8. Referential content
+9. Prerequisites
+10. Procedural content
+11. Troubleshooting content
+12. Further reading (conditional)
+
+![Screenshot of article with title, intro, permissions, product callout, conceptual section, procedural section, and table of contents labeled](/assets/images/contributing/illustration-of-article-contents.png)
+
+### Titles
+
+Titles fully describe what a page is about, and what someone will learn by reading it.
+
+Titles can be challenging. Use these general guidelines to help create clear, helpful, and descriptive titles. The guidelines for each content type in this article provide more specific title rules.
+
+#### Titles for all content types
+- Titles clearly describe what a page is about. They are descriptive and specific.
+  - Use: Browsing actions in the workflow editor
+  - Use: Example of configuring a codespace
+  - Avoid: Using the workflow editor sidebar
+  - Avoid: Example
+  - Titles have hard limits for length to keep them easy to understand (and easier to render on the site): 
+     - Category titles: 67 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 27 characters
+     - Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 30 characters
+     - Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 31 characters, ideally 20-25 characters
+- Titles are consistent across a content type
+  - See specific guidelines for each content type
+  - Titles aren’t repetitive––vary the verbs used for procedure or map topic titles when possible
+- Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products
+  - Use: "GitHub's billing plans"
+  - Avoid: "Billing plans for user and organization accounts"
+- Titles use consistent terminology
+  - Develop and follow patterns within a category or on similar subjects
+- Titles use terminology from the product itself
+- Write the title and the intro at the same time
+  - Use the intro to develop the ideas presented in the title
+  - See guidance on intros for more information
+- If it's hard to come up with a title, consider the content type. Sometimes trouble choosing a title indicates that another content type would fit better.
+- Think about how the title will appear in search results for multiple products
+  - What specific words do we need to include in the title or intro so that folks don’t mistake it for content about a different product?
+- Think about how the title will look in production
+
+### Product callout
+
+Use the product callout when a feature is available in specific products only and that availability cannot be conveyed by versioning alone. For example, if a feature is available for GHEC, GHES, and GHAE, you can version content about the feature for GHEC, GHES, and GHAE only. If a feature is available for Pro, Team, GHEC, GHES, and GHAE (but not Free), use a product callout to convey that availability.
+
+All product callouts are stored as reusables in [`gated-features`](https://github.com/github/docs/tree/main/data/reusables/gated-features) and added in YAML frontmatter for relevant articles.
+
+#### How to write a product callout
+- Product callouts follow a strict format, clearly identifying the feature and which products it’s available in. 
+- Product callouts also include a link to "GitHub’s products” and occasionally to another relevant article.
+- Examples:
+  - [Feature name] is available in [product(s)]. For more information, see "GitHub’s products.”
+  - [Feature name] is available in public repositories with [free product(s)], and in public and private repositories with [paid products]. For more information, see "GitHub’s products.”
+
+#### Examples of articles with product callouts
+Check the source files and `gated-features` to see how source content is written.
+- [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
+
+### Intro
+
+The top of every page has an intro that provides context and sets expectations, allowing readers to quickly decide if the page is relevant to them. Intros also are displayed in search results to provide contextual information to help readers choose a result.
+
+#### How to write an intro
+- Article intros are one to two sentences long.
+- Map topic and category intros are one sentence long.
+- API reference intros are one sentence long.
+  - The intro for an API page should define the feature so that someone knows whether the feature meets their needs without reading the entire article.
+- Intros contain a high-level summary of the page’s content, developing the idea presented in a title with more detail. 
+  - Use approachable synonyms of words in the page’s title to help readers understand the article’s purpose differently. Avoid repeating words from the title when possible. 
+- Intros are relatively evergreen and high-level, so they can scale with future changes to the content on the page without needing to be frequently updated.
+- For searchability, include keywords on the page's subject in the intro. 
+- When a term in the intro has an acronym we’ll use elsewhere in the article, indicate the acronym.
+- Intros generally don't contain permissions for any tasks contained within the article.
+
+### Permissions statements
+
+Every procedure includes a permissions statement explaining the role required to take the action described in the procedure, which helps people understand whether they'll be able to complete the task.
+
+Occasionally, it's relevant to mention required permissions in conceptual content, especially in standalone conceptual articles. Make sure to also include a permissions statement in related procedures (or write a longer article combining all of the content).
+
+#### How to write a permissions statement
+- When a single set of permissions applies to all procedures in an article, use the [permissions frontmatter](https://github.com/github/docs/tree/main/content#permissions). 
+- When an article contains multiple procedures and different permissions apply, include a separate permissions statement under each relevant header, before each procedure. 
+- Don't include permissions in an article’s intro.
+- Roles exist at different levels. Refer only to the role at the same level as the action. For example, you need admin access to a repository (repository-level role) to configure protected branches. You can get admin access to a repository by being an organization owner (organization-level role), but the repository-level role is what actually governs your ability to take the action, so that is the only role that should be mentioned in the permissions statement.
+- Language to use in a permissions statement:
+  - [ACCOUNT ROLE] can [ACTION].
+  - People with [FEATURE ROLE] access for a [FEATURE] can [ACTION].
+  - AVOID: [ACCOUNT ROLE] and people with [FEATURE ROLE] access for a [FEATURE] can [ACTION].
+
+#### Examples of permissions statements
+- Article with single permissions statement for multiple procedures: [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
+
+### Tool switcher
+
+Some articles have content that varies depending on what tool someone uses to complete a task, such as the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_desktop %}. For most content, the same conceptual or procedural information will be accurate for multiple tools. However, if the only way to make information clear and accurate is by distinguishing content by tool, use the tool switcher. Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts change based on what tool someone uses. For more information on using the tool switcher, see the [tool switcher content model](https://github.com/github/docs/blob/main/contributing/tool-switcher.md).
+
+### Table of contents
+Tables of contents are automatically generated. For more information see "[Autogenerated mini-TOCs](https://github.com/github/docs/tree/main/content#autogenerated-mini-tocs)."
+
+### Conceptual content
+Conceptual content helps people understand or learn about a topic. See "[Conceptual](#conceptual)" above.
+
+### Referential content
+Referential content provides structured information related to actively using a product or feature. See "[Referential](#referential)" above.
+
+### Prerequisites
+
+Prerequisites are information that people need to know before proceeding with a procedure, so that they can prepare everything they need before starting the task.
+
+#### How to write prerequisites
+- Write prerequisites immediately before a procedure's numbered steps.
+- You can use a list, a sentence, or a paragraph to explain prerequisites.
+- You can also use a separate prerequisites section when:
+  - The prerequisite information is very important and should not be missed.
+  - There's more than one prerequisite.
+- To repeat or highlight important information about data loss or destructive actions, you may also use a warning or danger callout to share a prerequisite.
+
+#### Title guidelines for prerequisites
+- When using a separate section, use a header called `Prerequisites`
+
+#### Examples of articles with prerequisites sections
+- [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)
+- [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-subdomain-isolation)
+
+### Procedural content
+Procedural content helps people complete tasks. See "[Procedural](#procedural)" above.
+
+### Troubleshooting content
+
+Troubleshooting content helps people avoid or work through errors. See "[Troubleshooting](#troubleshooting)" above.
+
+### Further reading
+
+Further reading sections highlight additional targeted articles that aren’t already included within the article’s content or sidebar. Use further reading sections sparingly when they provide real value.
+
+#### How to write a further reading section
+- Use a bulleted list. 
+- Use further reading sections sparingly and when they provide high value - see style guide for guidelines on linking.
+
+#### Title and format for further reading sections
+```
+### Further reading
+- "[Article title](article-URL)”
+- [External resource title](external-resource-URL) in External Resource Name
+```

content/contributing/writing-for-github-docs/creating-reusable-content.md

@@ -0,0 +1,46 @@
+---
+title: Creating reusable content
+shortTitle: Create reusable content
+intro: 'You can create reusable content that can be referenced in multiple content files.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About reusables
+
+Reusables are long strings of reusable text, such as paragraphs or procedural lists, that can be referenced in multiple content files.
+
+We use Markdown (instead of YAML) for reusables. Markdown makes it possible for our localization pipeline to split the strings into smaller translatable segments, leading to fewer translation errors and less churn when the source English content changes.
+
+Each reusable lives in its own Markdown file.
+
+The path and filename of each Markdown file determines what its path will be in the data object. For example, a file named `{% raw %}/data/reusables/foo/bar.md{% endraw %}` will be accessible as `{% raw %}{% data reusables.foo.bar %}{% endraw %}` in pages.
+
+Reusable files are divided generally into directories by task. For example, if you're creating a reusable string for articles about {% data variables.product.prodname_dotcom %} notifications, you'd add it in the directory `{% raw %}data/reusables/notifications/{% endraw %}`, in a file named `{% raw %}data/reusables/notifications/YOUR-REUSABLE-NAME.md{% endraw %}`. The content reference you'd add to the source would look like `{% raw %}{% data reusables.notifications.YOUR-REUSABLE-NAME %}{% endraw %}`.
+
+### Applying versioning to reusables
+
+Reusables can include Liquid conditionals to conditionally render content depending on the current version being viewed. <!-- For more information, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs)." -->
+
+## About variables
+
+Variables are short strings of reusable text.
+
+We use YAML files for variables.
+
+The path, filename, and keys within each YAML file determine what its path will be in the data object.
+
+For example, this YAML file, `{% raw %}data/variables/foo/bar.yml{% endraw %}`, contains two variables:
+
+```yaml
+# the YAML file can contain multiple short strings in one file
+meaning_of_life: 42
+
+# the strings can also be nested if needed
+nested:
+  values:
+    too: Yes!
+```
+
+The values would be accessible as `{% raw %}{% data foo.bar.meaning_of_life %}{% endraw %}` and `{% raw %}{% data foo.bar.nested.values.too %}{% endraw %}`.

content/contributing/writing-for-github-docs/creating-screenshots.md

@@ -0,0 +1,224 @@
+---
+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 %}."
+versions:
+  feature: 'contributing'
+product: '{% data reusables.contributing.product-note %}'
+---
+
+## About screenshots in {% data variables.product.prodname_docs %}
+
+There are positives and negatives to adding a screenshot. Screenshots make articles more visually scannable and make instructions easier to understand, especially for people who have difficulty reading. When supplied with alt text, screenshots help blind and low-vision users collaborate with sighted colleagues.
+
+On the other hand, screenshots privilege sighted users, add length and load time to articles, and increase the volume of content that needs to be maintained. When captured at different pixel dimensions and degrees of zoom than the reader is using, screenshots can be confusing.
+
+Therefore, we only add screenshots to {% data variables.product.prodname_docs %} when they they meet our criteria for inclusion.
+
+## Criteria for including a screenshot
+
+Use a screenshot to complement text instructions when an element of the user interface (UI) is hard to find:
+
+- The element is small or visually subtle.
+- The element is not immediately visible. For example, the element is contained in a dropdown menu.
+- The interface has multiple competing choices that can cause confusion.
+
+Do not use screenshots for procedural steps where text alone is clear, or to show code commands or outputs.
+
+## Examples of the criteria for inclusion
+
+To help you determine whether to add a specific screenshot, consider the following examples of screenshots that do and do not meet our criteria for inclusion.
+
+### Screenshots that meet the criteria
+
+The following screenshots do meet our criteria for inclusion.
+
+#### The UI element is small or visually subtle
+
+The edit button for a repository's social media preview image is small and visually unobtrusive. It may be hard to find among the other repository settings.
+
+![Screenshot of an article showing text instructions and a UI screenshot for editing a social media image on a GitHub repository.](/assets/images/contributing/screenshot-yes-social-preview.png)
+
+The screenshot also gives a visual reference for the aspect ratio required.
+
+#### The UI element is not immediately visible
+
+Options to clone a gist are contained under a dropdown menu labeled "Embed."
+
+![Screenshot of an article showing instructions and a UI screenshot for cloning a gist on GitHub.](/assets/images/contributing/screenshot-yes-clone-gist.png)
+
+The screenshot is helpful to locate the correct option in the menu, which is not visible until the dropdown is opened.
+
+#### The interface has multiple choices that can cause confusion
+
+There are three elements that could be interpreted as "settings" on the main page for a repository: the "Settings" tab, the gear icon in the "About" section of the right sidebar, and the account settings accessed via the profile picture.
+
+![Screenshot of an article showing instructions and a UI screenshot for locating the Settings page in a GitHub repository.](/assets/images/contributing/screenshot-yes-repository-settings.png)
+
+The screenshot is helpful to find the correct option.
+
+### Screenshots that do not meet the criteria
+
+The following screenshots do not meet our criteria for inclusion.
+
+#### The UI element is easy to find
+
+The "Create repository" button is visually prominent through size, color, and placement. There are few competing choices.
+
+![Screenshot of an article showing instructions and a UI screenshot for the final step in creating a new repository on {% data variables.product.prodname_dotcom %}.](/assets/images/contributing/screenshot-no-create-repository.png)
+
+Text instructions are adequate to help the user complete the step.
+
+#### The UI has few, straightforward choices
+
+Simple and straightforward options, such as selecting or deselecting a checkbox, do not need a visual support.
+
+![Screenshot of an article showing instructions and a UI screenshot for requiring contributors to sign off on web-based commits.](/assets/images/contributing/screenshot-no-require-signoff.png)
+
+Text instructions are adequate to help the user complete the step.
+
+There are also two accessibility implications of including the full sentence of text below the checkbox in the screenshot:
+
+- The sentence is hard to read for low-sighted users, because it's small and not as crisp as HTML text.
+- A person using a screen reader won't have access to the information, because it will not fit within alt text character limits. Including the text in the instructions would remedy this, but would be unnecessarily wordy.
+
+## Requirements for screenshots
+
+In addition to the criteria for inclusion, screenshots must meet the following requirements.
+
+### Technical specifications
+
+- PNG file format
+- Static images only (no GIFs)
+- 144 dpi
+- 750–1000 pixels wide for full-column images
+- File size of 250 KB or less
+- Descriptive file names, such as `gist-embed-link.png` instead of `right_side_page_03.png`
+
+### Accessibility
+
+To meet the needs of more users, screenshots must:
+
+- Be accompanied by complete instructions in the procedural step, with no information conveyed entirely in visual form.
+- Be full contrast, as in the interface itself, with nothing obscured or reduced in opacity or color contrast.
+- Have alt text that describes the content of the image and the appearance of its highlighting, if any. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#alt-text)."
+- Be clear and crisp, with text and UI elements as legible as possible.
+
+### Visual style
+
+- Show a UI element with just enough surrounding context to help people know where to find the element on their screen.
+- Reduce negative space by resizing your browser window until optimal.
+- Show interfaces in light theme wherever possible.
+  - For {% data variables.product.prodname_dotcom %}, select "Light default" in your appearance settings. For more information, see "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-your-theme-settings)."
+  - For VSCode, select "GitHub light default" in the free [GitHub Theme](https://marketplace.visualstudio.com/items?itemName=GitHub.github-vscode-theme) extension.
+  - If the software you need to screenshot is available in dark mode only, it's fine to use dark mode.
+- If your username and avatar appear, replace them with @octocat's username and [avatar](https://avatars.githubusercontent.com/u/583231?v=4). Use the developer tools in your browser to replace your username with `@octocat` and to replace the URL of your avatar with `https://avatars.githubusercontent.com/u/583231?v=4`.
+- Do not include a cursor.
+
+#### Visual style for dropdown menus
+
+If the primary goal in showing a dropdown menu is to help the reader locate the menu itself, show the menu closed.
+
+![Screenshot of an article showing instructions and a UI screenshot for selecting a folder as the publishing source for {% data variables.product.prodname_pages %}.](/assets/images/contributing/screenshot-yes-pages-menu.png)
+
+If the primary goal in showing a dropdown menu is to help the reader distinguish among options within the menu, show the menu open. Capture open menus without focus (cursor or hover state). Showing menu items with a white background ensures contrast with the dark orange outline, where present.
+
+![Screenshot of an article showing instructions and a UI screenshot for locating the "Settings" menu item in the GitHub user account menu.](/assets/images/contributing/screenshot-yes-account-menu.png)
+
+## Highlighting elements in screenshots
+
+To highlight a specific UI element in a screenshot, use our special theme for [Snagit](https://www.techsmith.com/screen-capture.html) to apply a contrasting stroke around the element.
+
+The stroke is the color `fg.severe` in the [Primer Design System](https://primer.style/design/) (HEX #BC4C00 or RGB 188, 76, 0). This dark orange has good color contrast on both white and black. To check contrast on other background colors, use the [Color Contrast Analyzer](https://www.tpgi.com/color-contrast-checker/).
+
+![Screenshot of four options menus on a GitHub repository. The menu labeled "Fork" shows a fork count of 58.5k and is outlined in dark orange.](/assets/images/contributing/repository-fork-button.png)
+
+### Importing the {% data variables.product.prodname_docs %} theme into Snagit
+
+1. To download the Snagit theme, navigate to [`snagit-theme-github-docs.snagtheme`](https://github.com/github/docs/blob/main/contributing/images/snagit-theme-github-docs.snagtheme) in the `github/docs` repository, then click {% octicon "download" aria-label="Download raw content" %}.
+
+   ![Screenshot of the file view for "snagit-theme-github-docs.snagtheme." In the header of the file, a button labeled with a download icon is outlined in dark orange.](/assets/images/contributing/download-snagit-theme.png)
+1. Open Snagit, then select the **Shape** tool.
+1. Under "Quick styles," select **Import**.
+1. Select the Snagit theme from your computer's files. This will install the shape preset.
+1. Optionally, to add the theme to your favorites, star the dark orange rectangle.
+
+### Adding a highlight to a screenshot
+
+1. Open a screenshot in Snagit.
+1. To set pixel depth (resolution) and pixel width, below the image canvas, open the "Resize image" dialog.
+
+   - Pixel depth: 144dpi (equivalent to "2x" on Snagit for Mac)
+   - Pixel width: 1000 pixels maximum
+
+   {% note %}
+
+   **Note:** On Windows, you may need to select **Advanced** to change the resolution. Ensure **Use resampling** is disabled.
+
+   {% endnote %}
+1. With the {% data variables.product.prodname_docs %} theme open in the Shapes sidebar, select the dark orange rectangle.
+1. Drag and drop across the image to create a rectangle.
+1. Adjust the rectangle's height and width by dragging edges. Do not adjust the corner rounding, which should remain 4 px. Adjust the space between the UI element and the stroke so it's about the width of the stroke itself.
+1. Export image to PNG.
+
+{% note %}
+
+**Note:** A bug in Snagit may corrupt the corner rounding, causing rectangles to become ovals. If this occurs, delete and reinstall the {% data variables.product.prodname_docs %} theme (Windows and Mac), or click and drag the yellow dot at the top right of the shape to reset corner rounding to 4 px (Mac only).
+
+{% endnote %}
+
+## Replacing screenshots
+
+When replacing an existing image, best practice is to retain the image's filename.
+
+If you must change an image filename, search the repository for other references to that image and update all references to the original filename.
+
+If the image is used in deprecated versions of {% data variables.product.prodname_ghe_server %} documentation, don't change the filename.
+
+## Versioning images in Markdown content
+
+Some images apply to all {% data variables.product.prodname_dotcom %} plans ({% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_cloud %}, and {% data variables.product.prodname_ghe_server %}). In this case, there is no versioning required.
+
+When an image does differ from plan to plan, or changes in a newer release of {% data variables.product.prodname_ghe_server %}, the image need to be versioned with Liquid conditional statements. You may need to add this versioning when the content is initially created, or you may need to add it when the content is updated for a feature update or {% data variables.product.prodname_ghe_server %} release.
+
+### Image locations
+
+Images are located in the `/assets/images` directory. This directory has some sub-directories that can be used to organize content by plan and release number.
+
+Directory | Usage
+--------- | ------
+`/assets/images` | Images that are not specific to any {% data variables.product.prodname_enterprise %} product.
+`/assets/images/enterprise/enterprise-server` | Images that are applicable to all releases of {% data variables.product.prodname_ghe_server %} (GHES), or are applicable to the current release and future releases.
+`/assets/images/enterprise/<release number>`, such as `/assets/images/enterprise/3.0/` | When an image is changed in a new GHES release, add the new image to the original location, and move the old image to the directory corresponding to the latest release that the image applies to.
+
+### Example: An image differs between plans
+
+When there are differences between plans, you can use Liquid conditionals to version the two images.
+
+```{% raw %}
+{% ifversion fpt or ghec %}
+![An image of foo bar for GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud](/assets/images/foo/bar.png)
+{% else %}
+![An image of foo bar for GHES](/assets/images/enterprise/foo/bar.png)
+{% endif %}{% endraw %}
+```
+
+### Example: An image is updated in a new {% data variables.product.prodname_ghe_server %} release
+
+If an image will change for {% data variables.product.prodname_ghe_server %} 3.10, and the updated image will be used for all future versions of {% data variables.product.prodname_ghe_server %}, move the existing image to `/assets/images/enterprise/3.10`, then add the new image to the original location, `/assets/images/enterprise/foo/bar.png`.
+
+Your Liquid conditional would look like this:
+
+```{% raw %}
+{% ifversion fpt or ghec %}
+![An image of foo bar](/assets/images/foo/bar.png)
+{% elsif ghes < 3.10 %}
+![An image of foo bar for GHES 3.9 and lower](/assets/images/enterprise/3.5/foo/bar.png)
+{% else %}
+![An image of foo bar for GHES 3.10+](/assets/images/enterprise/foo/bar.png)
+{% endif %}{% endraw %}
+```
+
+When the 3.10 release is deprecated, the `/assets/images/enterprise/3.10` directory will be removed.
+
+The numbered release directory should contain images that apply to that release number only or to that release number and earlier. For example, images in `/assets/images/enterprise/2.22` should contain images that apply to 2.22 only or 2.22 and earlier.

content/contributing/writing-for-github-docs/index.md

@@ -0,0 +1,18 @@
+---
+title: Writing for GitHub Docs
+shortTitle: Writing for GitHub Docs
+intro: 'Learn about writing for {% data variables.product.prodname_docs %}, our content model, and how to follow our style guide.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+children:
+  - /style-guide
+  - /content-model
+  - /about-githubs-documentation-philosophy
+  - /writing-content-to-be-translated
+  - /using-videos-in-github-docs
+  - /creating-reusable-content
+  - /content-design-principles
+  - /creating-screenshots
+  - /templates
+---

content/contributing/writing-for-github-docs/templates.md

@@ -0,0 +1,381 @@
+---
+title: Templates
+intro: 'This article contains starter templates for the different content types used in {% data variables.product.prodname_docs %}.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## Conceptual article template
+
+Use the content model for full instructions and examples on how to write conceptual content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#conceptual)."
+
+```yaml
+{% raw %}---
+title: 'About <subject>'
+shortTitle: '<subject>'
+intro: 'Article intro. See tips for a great intro below.'
+product: "optional product callout"
+type: overview
+topics:
+  - topic
+versions:
+  - version
+---
+
+{% comment %} 
+- Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#conceptual to write this article.
+- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model
+- For product callout info, see https://github.com/github/docs/tree/main/content#product
+- For product version instructions, see https://github.com/github/docs/tree/main/content#versioning
+- Remove these comments from your article file when you're done writing.
+{% endcomment %}
+
+## A section here
+
+{% comment %} 
+Write one or two paragraphs about the main idea of your topic, as a summary. 
+Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. 
+{% endcomment %}
+
+## Another section here
+
+{% comment %} 
+Write one or two paragraphs about another element of your topic. 
+Keep adding headers and sections until you've completed your article.  
+{% endcomment %}
+
+## Further reading
+
+{% comment %} 
+Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. 
+{% endcomment %}
+
+- "[Article title](article-URL)"{% endraw %}
+```
+
+## Referential article template
+
+Use the content model for full instructions and examples on how to write referential content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#referential)."
+
+```yaml
+{% raw %}---
+title: Nouns describing your subject
+shortTitle: <subject> # Max 31 characters
+intro: 'Article intro. See tips for a great intro below.'
+product: "{{ optional product callout }}"
+type: reference
+topics: 
+  - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
+versions:
+  - <version>
+---
+
+{% comment %} 
+Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#referential to write this article.-- >
+Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model 
+For product callout info, see https://github.com/github/docs/tree/main/content#product 
+For product version instructions, see https://github.com/github/docs/tree/main/content#versioning 
+Remove these comments from your article file when you're done writing 
+{% endcomment %}
+
+## A section here
+
+{% comment %} 
+Write one or two paragraphs about the main idea of your topic, as a summary. 
+Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. 
+{% endcomment %}
+
+## Another section here
+
+{% comment %} 
+Write one or two paragraphs about another element of your topic. 
+Keep adding headers and sections until you've completed your article.  
+{% endcomment %}
+
+## Further reading
+
+{% comment %} 
+Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. 
+{% endcomment %}
+
+- "[Article title](article-URL)"{% endraw %}
+```
+
+## Procedural article template
+
+Use the content model for full instructions and examples on how to write procedural content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#procedural)."
+
+```yaml
+{% raw %}---
+title: Start with a present participle
+shortTitle: <subject> # Max 31 characters
+intro: 'Article intro. See tips for a great intro below.'
+product: "{{ optional product callout }}"
+type: how_to
+topics: 
+  - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
+versions:
+  - <version>
+---
+
+{% comment %} 
+Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#procedural to write this article.-- >
+Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model 
+For product callout info, see https://github.com/github/docs/tree/main/content#product 
+For product version instructions, see https://github.com/github/docs/tree/main/content#versioning 
+Remove these comments from your article file when you're done writing 
+{% endcomment %}
+
+## Procedural section header here
+
+{% comment %} 
+Include prerequisite information or specific permissions information here. 
+Then write procedural steps following the instructions in https://docs.github.com/contributing/writing-for-github-docs/style-guide#procedural-steps. 
+Check if there's already a reusable string for the step you want to write in https://github.com/github/docs/tree/main/data/reusables. Look at the source file for a procedure located in the same area of the user interface to find reusables. 
+{% endcomment %}
+
+## Optionally, another procedural section here 
+
+{% comment %} 
+Keep adding procedures until you've finished writing your article. 
+{% endcomment %}
+
+## Further reading
+
+{% comment %} 
+Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. 
+{% endcomment %}
+
+- "[Article title](article-URL)"{% endraw %}
+```
+
+## Quickstart article template
+
+Use the content model for full instructions and examples on how to write quickstarts. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#quickstart)."
+
+```yaml
+{% raw %}---
+title: Quickstart title
+shortTitle: <subject> # Max 31 characters
+intro: 'Article intro. Highlight that the guide is quick and to the point.'
+type: quick_start
+topics: 
+  - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
+versions:
+  - <version>
+---
+
+{% comment %} 
+Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#quickstart to write this article.
+For product version instructions, see https://github.com/github/docs/tree/main/content#versions.
+The entire quickstart should be about 600 words long or take about five minutes to read.
+Remove these comments from your article file when you're done writing 
+{% endcomment %}
+
+## Introduction
+
+{% comment %} 
+Build on the quick phrasing above by
+- Clarifying the audience
+- Clearly stating prerequisites and prior knowledge needed
+- Stating what the user will accomplish or build
+{% endcomment %}
+
+## Step one: Action the user will take
+
+{% comment %} 
+In one sentence, describe what the user will do in this step 
+Steps should break down the tasks the user will complete in sequential order 
+Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. 
+{% endcomment %}
+
+### Task chunk
+
+{% comment %} 
+A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. 
+An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets 
+For UI based tasks, include the button or options the users should click 
+If the task adds code, include the code in context (don't just show `needs setup` show the entire `setup` and `dependent` jobs) 
+{% endcomment %}
+
+### Another task chunk
+
+## Step 2: Do the next thing
+
+{% comment %} 
+Rinse and repeat, adding steps and tasks until the tutorial is complete 
+{% endcomment %}
+
+## Next steps
+
+{% comment %} 
+Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps. Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Skills. 
+{% endcomment %}{% endraw %}
+```
+
+## Tutorial article template
+
+Use the content model for full instructions and examples on how to write tutorials. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#tutorial)."
+
+```yaml
+{% raw %}---
+title: Tutorial title
+shortTitle: <subject> # Max 31 characters
+intro: 'Article intro. See tips for a great intro below'
+product: "{{ optional product callout }}"
+type: tutorial
+topics: 
+  - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
+versions:
+  - <version>
+---
+
+{% comment %}  
+Follow the instructions in https://docs.github.com/contributing/writing-for-github-docs/content-model#quickstart to write this article.
+Great intros clarify who the tutorial is intended for, state what the user will accomplish, and state the technologies that will be used.
+For product callout info, see https://github.com/github/docs/tree/main/content#product 
+For product version instructions, see https://github.com/github/docs/tree/main/content#versioning 
+Remove these comments from your article file when you're done writing 
+{% endcomment %}
+ 
+## Introduction
+
+{% comment %} 
+The tutorial introduction should include the following in a short paragraph -
+
+- Clarify audience
+- State prerequisites and prior knowledge needed
+- State what the user will accomplish or build and the user problem it solves
+- Link to an example of the project the user will complete 
+{% endcomment %}
+
+## Step 1: Action the user will take
+
+{% comment %} 
+In one sentence, describe what the user will do in this step 
+Steps should break down the tasks the user will complete in sequential order 
+Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. 
+{% endcomment %}
+
+### Task chunk
+
+{% comment %} 
+A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. 
+An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets 
+For UI based tasks, include the button or options the users should click 
+If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) 
+{% endcomment %}
+
+### Another task chunk
+
+## Step 2: Do the next thing
+
+{% comment %} 
+Rinse and repeat, adding steps and tasks until the tutorial is complete
+Remember to show code snippets in context 
+{% endcomment %}
+
+## Further reading
+
+{% comment %} 
+Include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial 
+{% endcomment %}
+
+- "[Article title](article-URL)"{% endraw %}
+```
+
+## Language guides for GitHub Actions
+
+Use the content model for full instructions and examples on how to write for {% data variables.product.prodname_docs %}. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/content-model)."
+
+
+```yaml
+{% raw %}---
+title: Guide title
+shortTitle: <subject> # Max 31 characters
+intro: 'Article intro. See tips for a great intro below'
+product: "{{ optional product callout }}"
+type: tutorial
+topics: 
+  - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js
+versions:
+  - <version>
+---
+
+{% comment %} 
+- Great intros clarify who the guide is intended for, state what the user will accomplish, and state the technologies that will be used. 
+- Intros are typically 1-3 sentence summaries, with a longer "Introduction" section that follows.
+- Remove these comments from your article file when you're done writing
+{% endcomment %}
+
+## Introduction
+
+{% comment %} 
+The language guide introduction should include the following in a short paragraph -
+- Clarify audience.
+- State prerequisites and prior knowledge needed.
+- Should the user have read any other articles?
+- State what the user will accomplish or build and the user problem it solves.
+{% endcomment %}
+
+## Starting with the <language> workflow template
+
+{% comment %} 
+Language guides typically walk through and build upon a starter workflow template. If that format doesn't work, you can include a boilerplate workflow.
+- Link to the GitHub Actions CI starter workflow as the boilerplate reference code and then walk through and build on that code in this guide - https://github.com/actions/starter-workflows/tree/master/ci
+- Provide instructions for adding the starter workflow template to a repository.
+- Include the starter template workflow code.
+{% endcomment %}
+
+## Running on different operating systems
+
+{% comment %} 
+Include a brief overview of how to choose the runner environment. These should be alternatives to what operating system is presented in the starter workflow/boilerplate template.
+{% endcomment %}
+
+## Configuring the <language> version
+
+{% comment %} 
+- Describe when and how to use available setup actions that configure the version of the language on the runner (ex. actions/setup-node).
+- How does the setup action configure the version and what happens when the version isn't supported in the environment. What is the default version, when no version is configured.
+- Include any additional features the setup action might provide that are useful to CI.
+- If applicable, provide examples of configuring exact versions or major/minor versions.
+- Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project. 
+- Provide examples of configuring matrix strategies.
+- Link out to any docs about available software on the GitHub-hosted runners. (Ex. https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners).
+- Include code samples.
+{% endcomment %}
+
+## Installing dependencies
+
+{% comment %} 
+- Include example of installing dependencies to prepare for building and testing.
+- Are there any dependencies or scenarios where people might need to install packages globally?
+- Include examples of common package managers.
+- If the language is supported by GitHub Packages, include an example installing dependencies from GitHub.
+- Include code samples.
+{% endcomment %}
+
+## Caching dependencies
+
+{% comment %} 
+Include an example of restoring cached dependencies. We'll want to link out to the article about caching for more information (https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows).
+{% endcomment %}
+
+## Building your code
+
+{% comment %} 
+- Include any compile steps.
+- Include any test commands.
+- Note that you can use the same commands that your repository needs to build and test your code by simply replacing the commands in the `run` keyword.
+- Include any basic examples or commands specific to test frameworks.
+- Include any common databases or services that might be needed. If so, we can link out to the services guides in the docs (https://docs.github.com/en/actions/configuring-and-managing-workflows/using-databases-and-service-containers).
+{% endcomment %}
+
+## Packaging workflow data as artifacts
+
+{% comment %} 
+This section can simply link out to https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts or provide additional information about which artifacts might be typical to upload for a CI workflow.
+{% endcomment %}{% endraw %}
+```

content/contributing/writing-for-github-docs/using-videos-in-github-docs.md

@@ -0,0 +1,153 @@
+---
+title: Using videos in GitHub Docs
+shortTitle: Using videos
+intro: 'This guide explains how to create videos that support user needs for {% data variables.product.prodname_docs %}.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About videos in {% data variables.product.prodname_docs %}
+
+Videos are used rarely in the {% data variables.product.prodname_docs %}. When videos are necessary to provide the best user experience for an article, they are used together with written text. Videos are not a replacement for written content. Videos should never be the only way information is communicated because they are more difficult to keep up to date and are not accessible to everyone.
+
+
+Use these guidelines to determine if a video is appropriate to include in an article or on a landing page in the docs.
+
+If you add a link to a video or embed a video in the {% data variables.product.prodname_docs %}, add the video's metadata to the "[Videos in {% data variables.product.prodname_docs %}](https://github.com/github/docs/blob/main/contributing/videos-in-github-docs.md)" file in the `github/docs` repository.
+
+The Docs team does not create or maintain video content. Videos are purely supplemental to help communicate significant or complex topics, and should be used sparingly because they are not a content type owned by the Docs team.
+
+## Video checklist
+
+Use this checklist to quickly determine if a video might be appropriate to add to an article or landing page.
+
+- Is the video the only way to communicate the information?
+- Does {% data variables.product.prodname_dotcom %} own the video?
+- Is the video well produced? (See the "[Best practices](#best-practices)" section for more information.)
+- Is the video accessible to the broadest group of users possible? (See the "[Accessibility requirements](#accessibility-requirements)" section for more information.)
+- Is the video less than five minutes long?
+- Does the video have a specific audience and purpose in the docs? If it is only relevant to a particular product or feature, you must version it. See the "[Versioning](#versioning)" section for more information.
+
+If you answer "no" to any of these items, the video is not suitable for adding to the {% data variables.product.prodname_docs %}.
+
+### Maintaining videos
+
+If a video has a maintenance schedule or a team directly responsible for auditing and updating the content if it becomes out of date, you can include the video without any additional steps.
+
+If the video does not have a maintenance schedule, create an issue with an appropriate target date to review or remove the video.
+
+## Best practices
+
+Use these best practices to help determine if a video is well produced and is of a high enough quality to be included in the {% data variables.product.prodname_docs %}.
+
+Good videos introduce an instructional agenda that includes steps and goals so that someone watching quickly knows what they will learn. Videos are demonstrative, both showing and explaining the relevant steps that are performed. Videos should be engaging and encouraging. Videos must be well produced to be included in the {% data variables.product.prodname_docs %}. A well produced video contains few barriers for people with disabilities, has professional narration (if it is a narrated video), has clear visuals, and comes from a trusted source such as {% data variables.product.prodname_dotcom %} or Microsoft.
+
+Videos are broadly grouped into three categories: product overviews, feature videos, and tutorials. These descriptions are generalizations of each video type. Some videos might not fit perfectly in one category, but can still be useful without meeting the exact guidelines.
+
+### Product overviews
+- **Purpose**: Briefly explain what the product is, showcase the main functionality, and get people interested
+- **Length**: Less than a minute
+- **Possible audiences**: People who want to know if a feature is useful for their goals, people who are new to {% data variables.product.company_short %} and trying to understand what the products do
+- **Possible locations in the docs**: Landing pages and guides
+
+### Feature videos
+- **Purpose**: Supplement conceptual or procedural content
+- **Length**: As short as possible, without exceeding five minutes. Break longer content into multiple shorter, focused videos
+- **Possible audiences**: People who are learning about or how to use a feature
+- **Possible locations in the docs**: Guides, conceptual articles, procedural articles
+
+### Tutorials
+- **Purpose**: Help novice users get going with a product, drive adoption, or explain complex functionalities
+- **Length**: Individual videos should be five minutes or less. Complex topics can have a series of shorter videos spread across an article. Total length should be a maximum of 15 minutes
+- **Possible audiences**: New users of features or products
+- **Possible locations**: Guides
+
+## When to use videos
+
+We might use videos instead of other visuals such as screenshots or diagrams when it is important to show movement or changes in state, like when someone navigates from one screen to another or demos a feature that involves progressing through multiple menus. However, screenshots or text may be sufficient to explain these procedures.
+
+Videos can also be helpful to introduce features or products where a 30 second video can supplement information that requires multiple paragraphs to write.
+
+Use videos that explain the value of the procedure or concept that they are showing.
+
+## When to not use videos
+
+Do not use videos for features that change quickly and may make videos out of date. Do not use videos that contradict the written content or violate any parts of the "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#alt-text)." Do not use videos that just show a task without explaining or elaborating on the procedure. Videos must be useful and relevant, which includes staying accurate over time.
+
+## Accessibility requirements
+
+These are the minimum requirements for a video to be included in the {% data variables.product.prodname_docs %}. If a video violates any of these requirements, it cannot be added to the docs.
+
+- No flashing or strobe effects
+- Must have closed captions. See "[Creating video captions](#creating-video-captions)" below for more information
+- No graphics overlap with where captions appear
+- Typography must be legible
+- Any overlays must have sufficient contrast ratios
+- Any text must be on the screen long enough to be read (the text should appear onscreen for longer than it takes to read it out loud twice)
+- Must have proofread descriptive transcripts for what happens scene-by-scene. See "[Creating video transcripts](#creating-video-transcripts)" below for more information
+- Videos do not autoplay
+
+### Creating video captions
+
+Videos must have human-generated captions before being added to the Docs site. You can use auto caption technology to help create the captions, but they must be proofread and edited for accuracy by a person. If the video hosting service has a native caption tool, like YouTube, you can use that tool to prepare captions or create a properly formatted `SRT` or `VTT` transcript file to upload with the video.
+
+Creating captions is part of the process of producing videos that can be accessed by more people, so the owner of a video being added to {% data variables.product.prodname_docs %} should provide captions.
+
+#### Guidelines for captions
+
+Where possible, captions should exactly match the words spoken in the video. Do not paraphrase or truncate captions, unless serious time constraints mean it would be difficult for someone to read the captions in the time given.
+
+Captions must be synchronized to appear at approximately the same time as the audio. Captions should always be timed to appear on screen at the moment the speaker begins talking. For fast speech, where it would be difficult to read captions timed precisely to the audio, you can extend the captions to stay on screen after the speech has finished.
+
+If a video has multiple speakers, identify the speakers in the captions. Do this by adding the speaker's name, or a descriptive name such as `Developer`, before the start of the sentence. For example: `Jimmy: Hello.`. You only need to do this when the speaker changes, not for every line of dialogue. If it's obvious from the visuals who is speaking, you do not need to identify the speaker.
+
+Captions must be one or two lines, and no more than 32 characters per line. Put each new sentence on a new line. If you need to break a line mid-sentence, do so at a logical point, for example after commas or before conjunctions like `and` or `but`.
+
+#### Adding and editing captions on YouTube
+
+For videos hosted on YouTube, see "[Add subtitles and captions](https://support.google.com/youtube/answer/2734796?hl=en&ref_topic=7296214)" and "[Edit or remove captions](https://support.google.com/youtube/answer/2734705?hl=en&ref_topic=7296214)" in the YouTube docs.
+
+### Creating video transcripts
+
+For every video linked or embedded in the docs, we must have a descriptive transcript of the video. Transcript articles are formatted like other articles, with YAML frontmatter and Markdown content. To add a transcript to the Docs site, create an article in [`content/video-transcripts`](https://github.com/github/docs/tree/main/content/video-transcripts), and include the transcript as the article's body text. Give the article a filename like `transcript-VIDEO-NAME.md` and a `title` frontmatter property of `Transcript - VIDEO NAME`. Add the article to the `index.md` file in the `video-transcripts` directory.
+
+Do not use Liquid variables or reusables to replace things like product names in the transcript. The transcript should be faithful to the audio in the video, and we should not change any text in the transcript as a result of updating a variable or reusable after the video was produced.
+
+Creating transcripts is part of the process of producing videos that can be accessed by more people, so the owner of a video being added to the docs site should provide the content for a transcript.
+
+You can use captions as the foundation for a transcript. Edit the captions to remove any timestamps and include the relevant information detailed below. A descriptive transcript includes a text version of both audio and visual information needed to understand the content of a video.
+
+- If a video has multiple speakers, identify the speakers in the transcript
+- Format the transcript in logical paragraphs, lists, and sections. If it helps people understand the content, you may add headers to sections. Consider how someone would get information from the transcript if they are not also viewing the video
+- Add any onscreen text, relevant visual elements, or non-speech sounds that are not included in the captions. Place these descriptions after the spoken text that accompanies them in the video. Format visual information in brackets. For example, `[Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]`
+- Add a `product_video` property to the transcript article's YAML frontmatter. The value of the `product_video` property is the YouTube URL of the video. The video's YouTube URL will display as an external link in the transcript article
+- At the end of the transcript, link to the landing page for the product the video is about using the pattern `For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page).`
+
+See "[Text Transcript with Description of Visuals](https://www.w3.org/WAI/perspective-videos/captions/#transcript)" in the W3C docs for more examples of audio and visual transcriptions.
+
+#### Linking to transcripts from externally hosted videos
+
+Add a link to the article with a video's transcript in the description of the video on the platform where it is hosted. For more information, see "[Edit video settings](https://support.google.com/youtube/answer/57404?)" in the YouTube documentation.
+
+#### Linking to transcripts for embedded videos
+
+In any content with an embedded video, add a `product_video_transcript` property below the `product_video` property in the YAML frontmatter. The value of `product_video_transcript` is a link to the transcript article in the `video-transcripts` directory.
+
+```YAML
+title: Example product landing page
+product_video: 'https://www.youtube-nocookie.com/embed/URL'
+product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE
+```
+
+## Titles for videos
+
+Titles should be descriptive and follow the guidelines for titles in "[AUTOTITLE](/contributing/writing-for-github-docs/content-model#titles)."
+
+## Versioning
+
+If a video is only relevant for specific {% data variables.product.prodname_dotcom %} products (Free, Pro and Team; {% data variables.product.prodname_ghe_server %}; {% data variables.product.prodname_ghe_managed %}; and {% data variables.product.prodname_ghe_cloud %}), the video must be versioned for those products. Use [Liquid](https://github.com/github/docs/blob/main/contributing/liquid-helpers.md) conditional statements to version the videos appropriately. The Liquid conditional versioning may need to be added when the content is initially created, or may need to be added when the content is updated for a feature update or {% data variables.product.prodname_enterprise %} release.
+
+## Video hosting
+
+Videos must be hosted somewhere that {% data variables.product.prodname_dotcom %} owns and can grant the Docs team access to. Videos should not track users or use cookies. Currently, {% data variables.product.prodname_dotcom %}'s videos are hosted on YouTube and added to the docs using the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) by changing the domain for the embedded URL from `https://www.youtube.com/VIDEO` to `https://www.youtube-nocookie.com/VIDEO`.

content/contributing/writing-for-github-docs/writing-content-to-be-translated.md

@@ -0,0 +1,77 @@
+---
+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.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About writing content that is translation-friendly
+
+Use the following guidelines to ensure the content you create can be successfully translated. For more information, see "[Style guide](/contributing/writing-for-github-docs/style-guide)."
+
+- Use examples that are generic and can be understood by most people.
+- Avoid examples that are controversial or culturally specific to a group.
+- Write in active voice.
+- Write simple, short, and easy-to-understand sentences.
+- Avoid using too many pronouns that can make text unclear.
+- Avoid using slang and jokes.
+- Avoid negative sentences.
+- Use industry-standard acronyms whenever possible and explain custom acronyms.
+- Use indicative mood.
+- Eliminate redundant and wordy expressions.
+- Avoid the excessive use of stacked modifiers (noun strings). The translator can misunderstand which noun is the one being modified.
+- Avoid invisible plurals in which it is not clear if the first noun is meant to be singular or plural.
+- Avoid nominalization.
+- Avoid using ambiguous modal auxiliary verbs.
+- Avoid gender-specific words.
+- Avoid prepositional phrases.
+- Avoid vague nouns and pronouns (vague sentence subject).
+- Keep inline links to a minimum. If they are necessary, preface them with a phrase such as "For more information, see "Link title." Alternatively, add relevant links to a "Further reading" section at the end of the topic.
+
+## Examples
+
+This section provides examples for how to follow our guidelines for writing translation-friendly documentation.
+
+### Avoid country specific information
+
+For example, avoid 800 numbers and country specific addresses. If necessary, mention what countries the information applies to.
+
+### Avoid the excessive use of stacked modifiers (noun strings)
+
+Lots of stacked modifiers can lead to incorrect translations because it's not easy to determine what modifies what. For example, use "Default source settings for the public repository" instead of "public repository default source settings."
+
+### Avoid invisible plurals
+
+For example, when using the term "file retrieval," it's unclear if you are retrieving one file or all files. Provide more context to eliminate ambiguity. In the example given, you can use "retrieving all the files" or "retrieving the source.md file."
+
+### Avoid nominalization
+
+For example, instead of "to reach a conclusion," use "conclude."
+
+### Avoid using ambiguous modal auxiliary verbs.
+
+Avoid using words such as "may" and "might." Be more clear to avoid ambiguity.
+
+### Avoid prepositional phrases
+
+Instead of writing "after trying many times" or "according to the repository log," write more directly. For example, "after trying three times."
+
+### Avoid vague nouns and pronouns
+
+Vague nouns and pronouns can make it unclear who or what you are referring to, especially when that content has to be translated. For example, "Maintainers and contributors have access to files and comments. In the pull request they make changes to it." In this sentence, it is not clear if the changes are being made to the file or comments. If a pronoun seems to refer to more than one antecedent, either reword the sentence to make the antecedent clear or replace the pronoun with a noun to eliminate ambiguity.
+
+### Keep inline links to a minimum.
+
+Where possible, clearly introduce links following our style guide. For example, instead of the following sentence:
+
+```markdown
+Read [more about OAuth2.](/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.
+```
+
+You can use this instead:
+
+```markdown
+OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth Apps](apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](/rest/reference/oauth-authorizations/#create-a-new-authorization)."
+```

content/index.md

@@ -76,6 +76,7 @@ children:
   - early-access
   - support
   - video-transcripts
+  - contributing
 childGroups:
   - name: Get started
     octicon: RocketIcon

contributing/videos-in-docs.md

@@ -0,0 +1,38 @@
+# Videos in GitHub Docs
+
+This file tracks metadata for videos embedded in GitHub Docs.
+
+Add the following metadata for every video added docs.
+
+```markdown{:copy}
+Title: Video title
+URL: YouTube.com/
+Description: One sentence
+Product: e.x. Projects
+Versions: e.x. fpt, GHES > 3.2
+Date added: YYYY-MM-DD
+Location: /where/in/docs
+Transcript: ./content/video-transcripts/filename
+```
+
+```
+Title: Codespaces - Your instant dev box in the cloud
+URL: https://www.youtube-nocookie.com/embed/_W9B7qc9lVc
+Description: A 1.5 minute overview of GitHub Codespaces.
+Product: Codespaces
+Versions: fpt, ghec
+Date added: 2021-05-11
+Location: /content/codespaces/index.md
+Transcript: /video-transcripts/transcript-codespaces-your-instant-dev-box-in-the-cloud
+```
+
+```
+Title: Using Projects for feature planning
+URL: https://www.youtube-nocookie.com/embed/yFQ-p6wMS_Y
+Description: Check out all the cool new things you can do with your GitHub Projects powered by GitHub Issues
+Product: Issues, Projects
+Versions: projects-v2
+Date added: 2023-05-09
+Location: /content/issues/index.md
+Transcript: /video-transcripts/transcript-using-projects-for-feature-planning
+```

data/features/contributing.yml

@@ -0,0 +1,6 @@
+# Contributing to GitHub Docs (how we docs)
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+  ghae: '*'

data/reusables/contributing/product-note.md

@@ -0,0 +1 @@
+Articles in the "Contributing to GitHub Docs" section refer to the documentation itself and are a resource for GitHub staff and open source contributors.

src/content-linter/tests/lint-files.js

@@ -463,6 +463,14 @@ describe('lint markdown content', () => {
     })
 
     test('placeholder string is not present in any markdown files', async () => {
+      // this article explains how to use todocs placeholder text so shouldn't fail this test
+      if (
+        markdownRelPath ===
+          'content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md' ||
+        markdownRelPath === 'content/contributing/collaborating-on-github-docs/index.md'
+      ) {
+        return
+      }
       const matches = rawContent.match(placeholderRegex) || []
       const placeholderStr = matches.length === 1 ? 'placeholder' : 'placeholders'
       const errorMessage = `

src/content-linter/tests/site-data-references.js

@@ -20,8 +20,17 @@ const pages = await loadPages()
 const getDataPathRegex =
   /{%\s*?(?:data|indented_data_reference)\s+?(\S+?)\s*?(?:spaces=\d\d?\s*?)?%}/
 
+const rawLiquidPattern = /{%\s*raw\s*%}.*?{%\s*endraw\s*%}/gs
+
 const getDataReferences = (content) => {
-  const refs = content.match(patterns.dataReference) || []
+  // When looking for things like `{% data reusables.foo %}` in the
+  // content, we first have to exclude any Liquid that isn't real.
+  // E.g.
+  //   {% raw %}
+  //     Here's an example: {% data reusables.foo.bar %}
+  //  {% endraw %}
+  const withoutRawLiquidBlocks = content.replace(rawLiquidPattern, '')
+  const refs = withoutRawLiquidBlocks.match(patterns.dataReference) || []
   return refs.map((ref) => ref.replace(getDataPathRegex, '$1'))
 }