Skip to content

Shared text and screenshots for Microsoft Docs content.

License

Notifications You must be signed in to change notification settings

d1ane-lee/reusable-content

 
 

Repository files navigation

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).

    Screenshot of service folders at root level.

  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.

  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:

  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.

About

Shared text and screenshots for Microsoft Docs content.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published