Skip to content

How playbook publishing works on Microsoft Learn

This page will help you understand how the playbook is published on MS Learn, and it will help you understand some of the differences with how playbook content is organized on MS Learn versus in our legacy playbook.

Adding and updating playbook content

Playbook contributors add and update playbook content by submitting Pull Requests to the playbook repo. This is true in both the existing opsplaybook repo and the new solutions-playbook-pr repo. The publishing process on the two repos is different, however.

Pull Request previews

Contributors can view a preview version of their changes on both the old and new systems:

  • Previews on opsplaybook: Internal and public preview sites are built for every PR. The preview sites use random names that are different for every PR.
  • Previews on solutions-playbook-pr: MS Learn creates a preview site for every PR that is hosted on an internal site called review.learn.microsoft.com. A queryString parameter named branch specifies the name of the PR to display.

Site publishing

Site publishing is a bit more complex on Microsoft Learn, though the process has some benefits (discussed below) that make it easier for us to use the review.learn.microsoft.com site to host our internal playbook.

Here's how the live sites are updated for each solution:

  • Publish opsplaybook to live site: The live playbook.microsoft.com sites are re-published to reflect changes when any PR is merged into the main branch.
  • Publish solutions-playbook-pr to live site: Merging to the main branch does not kick off publishing. Instead, Microsoft Learn publishes its live web site from a branch called live. Thus, publishing a change to the live learn.microsoft.com site requires two steps:

    1. Merge changes from a feature branch to main.
    2. Merge changes from main to live.

The following diagram shows how branches are used to publish playbook content to the live MS Learn site.

Branching in the Microsoft Learn repos

Using the main branch to host our internal content.

The Learn team likely has multiple reasons for their two-stage publishing process, though I imagine that showing preview content to internal-only folks is one of them.

We are using this functionality to allow us to provide an internal-only preview version of playbook content (i.e. to host our "internal playbook").

How internal and public content is published

Here's how we enable the internal and public versions of our playbook content on MS Learn:

  • Internal-only playbook: Users visit the review.learn.microsoft.com site to view internal only content. The URL path is the same for both internal an public content, so you (and other Microsoft employees) can simply add the review. text to the beginning of any playbook URL to see it's internal-only preview version.
  • Public playbook: We update the public version of the playbook using a PR that merges changes in main to the live branch. But there's a twist: A GitHub action runs on all PR targeted at the live branch to perform the following steps:
    • Verify that all pages being merged into the live branch are in the public ring.
    • Evaluate all embedded Jinja2 expressions to filter internal-only content from the public version of the pages.

Rings

We use "rings" to manage which pages and content are published to the public site. Here's how rings work:

  • All pages and content are included on the internal site, often referred to as the internal ring. (A page can be explicitly included in the internal ring, but it's not required.)
  • Pages that are added to the public ring are included in the public version of the playbook. Contributors make a page public by simply adding the public keyword to the rings array in the a page's frontmatter (aka metadata).
  • Jinja2 expressions can be added to the text of a Markdown page to remove words or lines from pages when they are published on the public site. This has the huge benefit of letting us publish different versions of the same page on the internal and public sites.

MS Learn does not natively support rings, but we have implemented custom support for them inside the GitHub actions that run when PRs are created to merge updates to the live branch.

Redirects from the old site to MS Learn

GitHub actions on solutions-playbook-pr