Learn Metadata Extension

The Learn Metadata Extension allows you to update metadata in the YAML headers of Learn Markdown files in bulk. The extension is particularly useful for reviewing a set of metadata in a tabular format and making updates as needed, in cases where a simple VS Code search and replace isn't appropriate. For example, suppose a Learn author changes jobs, and her articles across a repo need to be divided up between several other authors, but assignments don't map reliably to the repo folder structure. You can export metadata for the repo, find the articles assigned to the departing author, and change the values to other authors depending on the article title or other metadata.

Step 1: Extract metadata

First, you need to extract the metadata of interest into tabular form.

1. Hit F1 to open the VS Code command palette.
2. Start typing to filter and select "Learn: Metadata Extract".
3. In the window that opens, browse to the folder you want to extract for. This can be the repo root or any subfolder.
4. Optionally, type the name of one metadata field to extract, such as author. If you don't specify a field, all metadata will be extracted.
5. Click OK to confirm.
6. A .csv file structured as a comma-separated list will open side-by-side with you currently displayed VS Code file. You can edit the file directly in VS Code, or use the pop-up to go to the file in your Learn AUthoring folder and open the file in Excel or another editor of your choice.

Step 2: Update metadata

Next, review the metadata in the tabular format and make any desired changes, using the following available commands.

1. Find the TAG and VALUE of interest.
2. Edit the existing VALUE, if appropriate.
3. Edit the ACTION as appropriate.

For example, suppose you want to change the author of several files from meganbradley to adunndevster. In this case, you might take advantage of the filtering capabilities of Excel to scope to the TAG and VALUE you want to update:

Then, update the VALUE from meganbradley to adunndevster, and update the ACTION to OVERWRITE:

You can make other changes in the same file. For example, ms.assetid is a deprecated attribute, so you might choose to delete it from all files in the repo. In this case, you first filter on TAG equals ms.assetid, then change ACTION from IGNORE to DELETE for each instance:

Step 3: Apply changes

When you've finished making changes to the extracted file, it's time to apply them.

1. Save and close the .csv file.
2. Hit F1 to open the VS Code command palette.
3. Start typing to filter and select "Learn: Metadata Apply".
4. If prompted, navigate to the correct file to apply.
5. Click OK to confirm.
6. Verify your changes in VS Code before submitting a pull request on the repo.

Can I use this tool to inject new metadata fields into multiple topics?

Yes, but at present it must be done manually by adding a new row to the extracted file for each article you want to add the metadata to, and populating it with the full file path, the ACTION "ADD", the TAG, the VALUE, and the format. There's a feature in the Learn AUthoring Pack backlog to enable injecting metadata in bulk; to upvote this feature, please file an issue in this repo.

What about the format column?

In general, you shouldn't touch this. This advanced functionality allows you to change the format of values as follows:

Caution: If you change a value or list to the wrong format, the file might become invalid.