Minimal Path to Awesome

The shortest way to prepare your local copy of the project for development and testing.

Install prerequisites

Before you start contributing to this project, you will need Node.js@14 and npm@7 installed.

Get the local version of the CLI

• fork this repository
• clone your fork
• in the command line:
  • run npm i to restore dependencies
  • run npm run build to build the project
  • run npm test to run test and check current code coverage (check out this awesome article by Martin Lingstuyl for more information)
  • run npm link to install the project locally. This is useful if you want to test your changes to the CLI in the CLI itself. After linking the local package, you can start your local version of the CLI by typing in the command line m365.

If you installed the CLI globally using the npm i -g @pnp/cli-microsoft365 command, we recommend that you uninstall it first, before running npm link

After changing the code, run the npm run build command to rebuild the project and see your changes integrated in the local version of the CLI.

If you renamed files:

• in the command line:
  • run npm run clean to clean up the output folder
  • run npm run build to rebuild the project
  • run npm link to reinstall the project locally. Without this step, you will get an error, when trying to start the local version of the CLI.

Documentation

CLI for Microsoft 365 uses MkDocs to publish documentation pages. For simplicity, we recommend using the MkDocs Material Docker container which contains all dependencies installed.

Preview docs using the Docker container

If you're using Visual Studio Code and have the Docker extension installed, you can run preview the docs using the container either by executing the Run docs container task, or, if you have pulled the image previously, from the Images pane by running the MkDocs container interactively. This article explains working with Docker containers using VSCode in more detail.

Alternatively, you can run the container in command-line:

• on macOS:
  • run cd ./docs to change directory to where the docs are stored
  • run docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:8.3.6 to start the local web server with MkDocs and view the documentation in the web browser
• on Windows:
  • run docker run --rm -it -p 8000:8000 -v c:/projects/cli-microsoft365/docs:/docs squidfunk/mkdocs-material:8.3.6 to start the local web server with MkDocs and view the documentation in the web browser

Preview docs using MkDocs installed on your machine.

If you want, you can also install MkDocs on your machine. See more information about installing MkDocs on your operating system at http://www.mkdocs.org/#installation.

CLI for Microsoft 365 documentation currently uses mkdocs-material theme v8.3.6. See more information about installing mkdocs-material on your operating system at https://squidfunk.github.io/mkdocs-material.

In order to run documentation locally, you can install MkDocs with pip (the Python package manager) then install the appropriate mkdocs-material version:

pip install mkdocs mkdocs-material==8.3.6 pymdown-extensions==9.5 pygments==2.12

Once you have MkDocs installed on your machine, in the command line:

run cd ./docs to change directory to where the docs are stored run mkdocs serve to start the local web server with MkDocs and view the documentation in the web browser