About

This repository contains content included on Microsoft Learn repos that appears as part of articles on Microsoft Learn properties. There are multiple repositories that contain Microsoft Learn content and writers often need to have the same content appear in multiple repos.

The goal of this project is to have one repository for include files that need to be referenced in multiple repos.

Get help

Contact the Reusable Content Repo Admins group at [email protected] for help with merging PRs.

Example use case and workflow

Use case

You are a content developer updating multiple articles across multiple Microsoft Learn repositories. The same set of instructions for creating a GitHub secret appears in 20+ articles on Microsoft Learn across four different repositories. You need to update instructions and a corresponding screenshot quickly.

Workflow

1. Add a new folder to the reusable-content repo for your service at the root level. The folder name should match the MSProd, MSService, or MSSubService for your content set. (Note: we may need to update existing content to meet this standard).

   

2. In the folder, add an include file with your content that follows the Learn guidelines for using includes. The include file can reference images in a media folder and should include metadata values. For more information, see Include reusable content in articles.

   • GitHub Actions example: Authenticate with PAT
   • GitHub Actions example: Create Secrets with OpenID

3. Update .openpublishing.publish.config.json and add a section to dependent_repositories (Learn platform user manual). To include images, you need to include the build_entry_point value in the docsets_to_publish section of .openpublishing.publish.config.json in the path_to_root value of the dependent_repositories property. Here's an example of this json snippet from azure-devops-docs-pr (.openpublishing.publish.config.json file).

      {
     "path_to_root": "docs/reusable-content",
     "url": "https://github.com/MicrosoftDocs/reusable-content",
     "branch": "main",
     "branch_mapping": {}
   }

4. Within your doc set, add the include to your article with INCLUDE syntax. Your path should include the build entry point.

   [!INCLUDE [include](~/../docs/reusable-content/github-actions/authenticate-with-pat.md)]
   

   Example articles with include references:

   • Build custom virtual machine images with GitHub Actions and Azure
     • .openpublishing.publish.config.json file for azure-dev-docs
     • Build entry point is docs
   • Trigger an Azure Pipelines run from GitHub Actions
     • .openpublishing.publish.config.json file for azure-sql
     • Build entry point is azure-sql
   • Use GitHub Actions with Azure Machine Learning
     • .openpublishing.publish.config.json file for azure-docs
     • Build entry point is articles

5. Save and push your code. Verify that the include file appears within your article and that all images display.

Troubleshooting

Why can't I see my images?

If your images aren't showing up, first make sure that they are being added to the build. One the build report and verify in the Publish Files section that the images are included. Select each File Name to verify that the link works.

If the images are being added to the build but are not appearing, recheck that the path you are using to reference your images is correct. If you're including images from a media folder within your content folder (example: azure-cli), the image markdown will look like this.

[:::image type="icon" source="media/hdi-launch-cloud-shell.png" alt-text="Launch Azure Cloud Shell" :::](https://shell.azure.com) 

Why can't I see the entire include file?

For an include file to appear from the dependent repository (reusable-content), the branch names in the reusable-content repository and your primary repository need to match. When you are testing, first merge your PR in the reusable-content repository. Then, reference your file within .openpublishing.publish.config.json from using the main branch.

Can I use variable replacement in my include files?

Include files do not support variable replacement.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Legal Notices

Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the Creative Commons Attribution 4.0 International Public License, see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the LICENSE-CODE file.

Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Privacy information can be found at https://privacy.microsoft.com/en-us/

Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel or otherwise.