Skip to content

Migrating the playbook to Microsoft Learn

While the overall approach is the same, many updates are needed to make our pages work correctly on MS Learn. Most changes are simple things like updating links to reflect the different folder structure on MS Learn. While there is nothing difficult about such changes, it would be super time consuming if we were to make all changes manually.

Just like our existing publishing solution, Microsoft Learn content is written in Markdown format, with a separate .md file for each article. This means we can move all our content to MS Learn and continue working on it in the same way we currently do. If you are a playbook contributor, you will likely feel the contribution process is almost exactly the same. You will notice some differences in formatting and navigation, but you can probably work productively in the new repo by quickly reviewing a "cheat sheet" that explains differences.

While there are formatting and process differences in MS Learn, most contributors are likely to feel the overall content to feel that the process of updating content is thshould feel that working on the playbooMS Learn det We have created automation scripts and GitHub actions import playbook content from the opsplaybook repo to a new MS Learn-managed repo located at The import code runs dozens of transformations and validation checks to convert the playbook content into a format that fully supports Microsoft Learn's internal functionality and validation checks.

Making the playbook work on Microsoft Learn

Solutions Playbook content and code currently resides in the repo. Playbook contributors create pull requests on the opsplybook repo to add and modify playbook content.

The first step in publishing our playbooks on Microsoft Learn is to migrate our content to a new GitHub repo that is managed by the Microsoft Learn team and connected to their publishing systems. This repo, repo located at, has a slightly different folder structure than our existing opsplaybook repo, but it otherwise works very much like our existing repo.

The good news is that we have created scripts that automatically copies our existing playbook pages and updates them to work correctly on MS Learn. These scripts are very robust, and no manual intervention is required beyond running the scripts and creating a PR to merge the updates.

Details can be found in the Migration Process page.