microsoft/docs-scaffolding

Visual Studio Code extension used to create content for Microsoft Learn

README

📣 This repository has been ARCHIVED. Development will continue internally. Thank you for all of your contributions! 📣

This extension provides automation for creating a Learn module based on a pre-defined pattern and for updating module structure after creation.

The Learn team has defined several standard patterns for Learn modules, each serving a different customer need:

• Introduction modules introduce a product or technology.
• Choose modules help you decide between different products or technologies.
• Standard modules provide an approved sequence of unit types to help learners understand and apply concepts.

The Scaffolding extension lets content developers create a module in one of these patterns in just a few clicks, instead of having to manually create the series of folders, YAML files, and Markdown files that make up a module. Each generated unit contains required metadata, templatized content, and guidance to help users craft modules that follow Learn best practices. Finally, the extension provides automation to easily update module structure, such as adding, renaming, reordering, and deleting units.

Here's a brief demo of the basic functionality:

Update your Settings to auto-populate metadata

You can set some metadata in your VS Code extension settings so it's auto-populated when you scaffold a new module.

1. In the VS Code File menu, select Preferences then Settings.
2. Expand Extensions then find Docs Scaffolding Extension Configuration.
3. Under Microsoft alias, type your Microsoft alias (without @microsoft.com) if you're a Microsoft employee. Otherwise, leave it blank.
4. Under GitHub ID, type your GitHub ID.
5. Under Default prefix, type a default prefix for your modules, such as "learn".
6. Under Default product, type the product(s) your modules will generally apply to, such as "azure". To specify multiple products, separate with a comma, such as "azure, sql".
7. Leave the Learn template repo as specified; currently there's only one, although we might support others in the future.

Now, when you scaffold a module, the following will be auto-populated based on your specifications:

• ms.author metadata will be set to your Microsoft alias.
• author metadata will be set to your GitHub ID.
• products metadata will be set your default product(s).
• Module and unit UIDs will be prefixed with your default prefix.

Create a new module based on a pre-defined pattern

1. In the VS Code file explorer, select the parent folder where you want to create a new module.

2. Right-click and select Learn: Create new module.

3. In the pop-up menu, select the appropriate module pattern depending on the intent of your module.

4. In the text box, specify a title for you module, using the placeholder text (such as "Choose the best {product category} for {your purpose}") as a guide.

   

5. Press Enter. Now you'll se a child folder for your module with the following characteristics:

   • The folder name is the module title with certain words omitted (such as "the") or shortened (such as "application" to "app").
   • The folder contains a media sub-folder for storing images.
   • The folder contains an index.yml file that defines the structure of the module. Some metadata is pre-populated based on your selections in Settings. The UIDs of the child units are generated based on your specified default prefix, the module title, and the standard unit titles for your chosen pattern, including placeholders you'll need to replace.
   • The folder contains unit YAML files based on the chosen pattern. Each unit file contains standard YAML structure, metadata, and if appropriate an included reference to a corresponding Markdown content file. The file names include a numeric prefix that defines the order of the units.
   • The folder contains an includes sub-folder with unit Markdown files. Each Markdown file contains a content template to help you write unit content according to Learn best practices.

   For example, here's a newly scaffolded Choose module with the title "Choose the best module pattern for my module":

   

Rename a unit

After you scaffold a new module, you'll need to rename the units to replace the placeholders. For example, in our "Choose the best module pattern for my module" module, we'd update the unit file "2-identify-{product}-options.yml" as follows:

1. Right-click the unit YAML file in VS Code file explorer and select Learn: Rename unit.

   Important: All module structure updates must be initiated from the unit YAML files, not the corresponding Markdown files or the index.yml file.

2. In the pop-up text box, you'll see the current file name, minus the numeric prefix and file name extension.

   

3. Type in the new unit file name. For example, "identify-{product}-options" might become "identify-module-pattern-options". Press Enter.

4. Next, you'll be prompted to update the module title. This is the value of the title YAML field in the unit YAML file. You can optionally type a new title, or you can cancel out. You can update the title field within the YAML file at any time.

5. The following changes are made automatically based on your input:

   • The name of the YAML file is updated. For example, if you typed "identify-module-pattern-options" as the new file name for "2-identify-{product}-options.yml", the new file name will be "2-identify-module-pattern-options.yml".
   • The corresponding Markdown file in the includes folder is renamed. For example, "2-identify-{product}-options.md" is updated to "2-identify-module-pattern-options.md".
   • The reference to the included Markdown file is updated in the parent YAML file.
   • If the module has not yet been published live, the UID under units in index.yml is also updated, such as learn.choose-the-best-module-pattern-for-my-module.identify-module-pattern-options. If the module has already been published live, placeholders should already have been removed, and UIDs won't be updated because that would break live content relationships.
   • If you updated the unit title, the title field in the YAML file is updated.

You can use the rename functionality to update unit file names and titles at any time. Again, once the module has been published live the UIDs won't be updated, but other references will be.

Add a unit

You can add a new unit to a module. For example, the default number of choices in a Choose module is four, but what if you have five choices?

1. Right-click the unit YAML file where you want to add a new unit. For example, if you want to add a new unit at the fifth position in the module, right-click the unit with the prefix "5".
2. From the pop-up menu, choose the appropriate unit type.
3. Type the file name for the new unit, minus prefix and extension. Press Enter.
4. Optionally type the unit title. Press Enter.
5. The new unit YAML file is added with the appropriate numeric prefix based on where you inserted it. A corresponding Markdown file is added in the includes folder and referenced from the unit YAML, and a UID is added in the appropriate order under units in index.yml. The numeric prefixes of other files are updated as needed to reflect the new order.

Delete a unit

Similarly, what if your Choose module only needs three choices? You can delete a unit as follows:

1. Right-click the unit YAML file you want to delete in file explorer.
2. Select Learn: Delete unit.
3. The unit YAML file and its corresponding Markdown file are deleted, the UID is removed from units in index.yml, and numeric prefixes are updated to reflect the new order.

Reorder units

You can change the order of units in a module:

1. Right-click the unit YAML file you want to move in file explorer.
2. Select Learn: Move unit up or Learn: Move unit down as appropriate.
3. The numeric prefix of the moved file and any files below it are updated to reflect the new file order. The corresponding Markdown files and inclusions are updated to match, and the UID list under units in index.yml is reordered.
4. Repeat the operation as many times as necessary until your units are in the right order.

docs-scaffolding's Issues

Excessive template repo downloads

The extension appears to download and unzip a new copy of learn-scaffolding-main.zip without cleaning it up every time I open a new VSCode window. Can it be optimized at all?

Warning Message for Line Endings

Description

When the scaffolding completes it adds incorrect line endings for Mac.

warning: CRLF will be replaced by LF in learn-pr/azure/aks-azure-monitor-prometheus/1-introduction.yml.
The file will have its original line endings in your working directory
warning: CRLF will be replaced by LF in learn-pr/azure/aks-azure-monitor-prometheus/2-learning-content.yml.
The file will have its original line endings in your working directory
warning: CRLF will be replaced by LF in learn-pr/azure/aks-azure-monitor-prometheus/3-exercise.yml.
The file will have its original line endings in your working directory
warning: CRLF will be replaced by LF in learn-pr/azure/aks-azure-monitor

To Reproduce

1. On Mac/Linux create a new Learn module.
2. Commit the changes you will receive the above warnings.

ACTION REQUIRED: Microsoft needs this private repository to complete compliance info

There are open compliance tasks that need to be reviewed for your docs-scaffolding repo.

Action required: 4 compliance tasks

To bring this repository to the standard required for 2021, we require administrators of this and all Microsoft GitHub repositories to complete a small set of tasks within the next 60 days. This is critical work to ensure the compliance and security of your microsoft GitHub organization.

Please take a few minutes to complete the tasks at: https://repos.opensource.microsoft.com/orgs/microsoft/repos/docs-scaffolding/compliance

• The GitHub AE (GitHub inside Microsoft) migration survey has not been completed for this private repository
• No Service Tree mapping has been set for this repo. If this team does not use Service Tree, they can also opt-out of providing Service Tree data in the Compliance tab.
• No repository maintainers are set. The Open Source Maintainers are the decision-makers and actionable owners of the repository, irrespective of administrator permission grants on GitHub.
• Classification of the repository as production/non-production is missing in the Compliance tab.

You can close this work item once you have completed the compliance tasks, or it will automatically close within a day of taking action.

If you no longer need this repository, it might be quickest to delete the repo, too.

GitHub inside Microsoft program information

More information about GitHub inside Microsoft and the new GitHub AE product can be found at https://aka.ms/gim or by contacting [email protected]

FYI: current admins at Microsoft include @jamarw, @lamebrain, @bharney0, @adunndevster

Support virtual workspaces

👋 Hi there, Martin here, from the VS Code team.

Recently we've announced the Remote Repository feature that lets you browse and edit files and folders directly on GitHub.

Open Remote Repository... opens VSCode on a folder or workspace located on a virtual file system. We call this a virtual workspace. We observed that not all extension support this well, either because they can not, or they haven't thought about it.

It would be fantastic if you could test whether your extension can handle virtual workspaces:

Check out the Virtual Workspaces Extension Author Guide on how to do that.

When done, set the new virtualWorkspaces capability in your 'package.json'.

{
  "capabilities": {
    "virtualWorkspaces": true | false
  }
}

• Use "virtualWorkspaces": true if your extension is prepared for virtual workspaces
• Use "virtualWorkspaces": false if your extension should be disabled when a virtual workspace is opened

For questions and comments please use the Virtual Workspaces Tracking Issue.

Thanks for the support and the great work! ❤️

Extension causes high cpu load

• Issue Type: Performance
• Extension Name: docs-scaffolding
• Extension Version: 0.0.4
• OS Version: Windows_NT x64 10.0.19042
• VSCode version: 1.54.3

⚠️ Make sure to attach this file from your home-directory:
⚠️c:\Users\KONSTA~1\AppData\Local\Temp\docsmsft.docs-scaffolding-unresponsive.cpuprofile.txt

Find more details here: https://github.com/microsoft/vscode/wiki/Explain-extension-causes-high-cpu-load

Entering the settings values causes cursor focus to move and reload notification

Every time I type in the github id field or the microsoft alias field, the cursor jumps to the template field, and this dialog appears.

Support Workspace Trust

Hello 👋 I'm from the VS Code team.

Recently, we have been exploring a security feature we refer to as Workspace Trust. This feature is intended to centralize and unify a security conscious decision required by a variety of VS Code features. With workspace trust, the user will be able to declare whether or not they trust the folder that is opened in VS Code before these features are executed.

Why you should care

Your extension is incredibly popular with VS Code users! We want to make sure that those users have a delightful experience with workspace trust and that includes extension authors deciding how much of their extension is supported in an untrusted workspace.

Workspace Trust experience

You can enable the feature with the following setting security.workspace.trust.enabled. Once enabled, you will see the following dialog when opening folders in VS Code.

This dialog is important for allowing the user to make a decision early and understand the impact of their decision. Once you understand the feature, you may want to customize when to display the dialog using the setting security.workspace.trust.startupPrompt.

You can follow the development of Workspace Trust and provide feedback in issue #106488.

Workspace trust API

First off, all of what I am about to say can be found in issue #120251. That issue will include discussion of the feature and any updates to the feature.

The Workspace Trust extension API is now in stable. This allowed us to release the first cut of our guide for onboarding your extension to Workspace Trust. The API is small, so here is a quick look.

You can declare your extension to provide complete, partial or no support in untrusted workspaces using the untrustedWorkspaces capability in package.json.

The following example declares that the extension is supported completely in untrusted workspaces. In this case, the extension is enabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": true
  }
}

The next example declares that the extension is not supported in untrusted workspaces. In this case, the extension is disabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": false
  }
}

The third option is to declared limited support. There are three tools provided to you when you select the limited option.

First, if you have a setting that can be configured in the workspace but requires the workspace to be trusted in order to apply the workspace value, then you can include the setting using restrictedConfigurations array property in untrustedWorkspaces object. Doing so, VS Code will ignore the workspace value of these restricted settings when your extension reads these settings values using the VS Code Workspace Configuration API.

The following example declares the settings that are restricted in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": "limited",
    "restrictedConfigurations": [
      "markdown.styles"
    ]
  }
}

Next, you can also check and listen if the current workspace is trusted or not programmatically using the following API:

export namespace workspace {
  /**
   * When true, the user has explicitly trusted the contents of the workspace.
   */
  export const isTrusted: boolean;
  /**
   * Event that fires when the current workspace has been trusted.
   */
  export const onDidGrantWorkspaceTrust: Event<void>;
}

Lastly, you can hide commands or views declaratively with the isWorkspaceTrusted context key in your when clauses.

A far more detailed guide on how to onboard which will be updated as we receive feedback can be found in issue #120251.

Rollout plan

Workspace Trust will remain disabled for the month of May, but we are planning on enabling this by default in the future. To prepare for that day, we would love for you to try it out and provide feedback.

We'd love your feedback

Since this issue was created in an automated fashion, we won't be monitoring the responses in this issue (our notifications would explode!). Instead we ask you to drop questions, and feedback in issue #120251 as we've mentioned above.

We're excited to see what you do with workspace trust!

Can't run any of the create new module actions

Either from a right click or the command palette. If I try and run Learn: Create module in NEW folder the error I get is 'scaffoldModule' failed.

I've removed and re-added the Docs Authoring Pack - made sure I have the latest version of VS Code - still getting the error. Same for the create module in current folder. Is it relate to the 0.0.8 release?