Adding new script sample

The following article describes how to add a new sample to the CLI for Microsoft 365. Each new sample should be submitted by a PR.

Location

All samples may be found in the docs/docs/sample-scripts folder grouped in categories. CLI for Microsoft 365 script samples are synchronized to the Microsoft Sample Solution Gallery and therefore they need additional metadata to be specified in order to be presented correctly in the gallery.

Structure

Each sample needs to be stored in a separate folder. The folder name should be the same as the sample title (all whitespaces should be replaced with dashes). The sample folder should have the following structure:

my-new-sample/
├─ assets/
│  ├─ preview.png
│  ├─ sample.json
├─ index.mdx

• assets/sample.json - this file has additional metadata about the sample that is needed in order to properly synchronize the sample to the Microsoft Sample Solution Gallery. More details about the contents of this file may be found in the next chapter
• assets/preview.png - this image will be shown as the sample preview in the Microsoft Sample Solution Gallery. This could present the result of the script sample (ex. if your script adds list items to a SharePoint list the preview image could show a screen of the populated list).
• index.mdx - this is the main file that contains the sample title, description, author, tags, and the script (or scripts if the sample was developed in multiple technologies/languages)

Sample.json (sample metadata)

This file is needed in order to properly display the sample on the Microsoft Sample Solution Gallery. Please use the below template with information on how to fill in the file. All places marked with <> should be populated accordingly.

[
  {
    "name": "pnp-<Same as folder name ex. pnp-disable-tenant-wide-extension>",
    "source": "pnp",
    "title": "<Same as sample title in the index.md file ex. Disable specified Tenant-wide Extension>",
    "url": "<Url to the sample on the CLI for Microsoft 365 docs page ex. https://pnp.github.io/cli-microsoft365/sample-scripts/spo/disable-tenant-wide-extension>",
    "creationDateTime": "<Date when the sample was first created>",
    "updateDateTime": "<Date of the last update of the sample file>",
    "shortDescription": "<Short one liner description of the sample main goal or functionality>",
    "longDescription": [
      "<Long and detail description of the sample. Should be similar to the one used in the index.mdx file>"
    ],
    "products": [
      "<Name of the Microsoft 365 product this sample interacts with ex. SharePoint>"
    ],
    "categories": [],
    "tags": [
      "<Collection of tags related to the sample. Should be the same list as in defined in the index.mdx file. ex. provisioning, libraries>"
    ],
    "metadata": [
      {
        "key": "CLI-FOR-MICROSOFT365",
        "value": "<Provide the version of CLI which was used to develop the sample ex. v6.1>"
      }
    ],
    "thumbnails": [
      {
        "type": "image",
        "order": 100,
        "url": "https://raw.githubusercontent.com/pnp/cli-microsoft365/main/docs/docs/sample-scripts/<Sample folder path>/assets/preview.png",
        "alt": "preview image for the sample"
      }
    ],
    "authors": [
      {
        "gitHubAccount": "<GitHub account name>",
        "pictureUrl": "<Url to the GitHub account image ex. https://avatars.githubusercontent.com/u/123456789?v=4>",
        "name": "<Name>"
      }
    ],
    "references": [
      {
        "name": "Want to learn more about CLI for Microsoft 365 and the commands",
        "description": "Check out the CLI for Microsoft 365 site to get started and for the reference to the commands.",
        "url": "https://aka.ms/cli-m365"
      }
    ]
  }
]

Sample contents

The sample file should contain a title, a short description, an author, tags, and the script in code blocks. To help you get started you may use the below template.

---
tags:
  - provisioning
  - libraries
---

# Cool sample to add multiple lists in a sites

Author: [author name](https://link)

Short description of the sample functionality.

=== "PowerShell"

    ```powershell
    # m365 cli magic
    ```

=== "Bash"

    ```bash
    # m365 cli magic
    ```