Update the Docs¶
This documentation site is also open source and contributions like typo fixes, new articles, etc. are always welcome! The documents live in the same repo as the samples in the
Docs in the groupings directory are auto generated using MDLooper (see Tool considerations below for details) and edits to these docs should not be made directly. Any samples you submit will be added to these when your Pull Request is accepted.
Items in the tools/html-formatter-generator are part of the tool build and should not be edited directly. If you are interested in contributing to the HTML to Formatter Generator tool, please consult the ./tools.md for details.
Updating existing docs¶
Creating new docs¶
Adding / referencing images¶
If you want to do more than just write or edit documentation, please ask first. This includes things like:
- Adding new MkDocs plugins
- Altering primary logos
- Changing theme values
- Adding functionality through configuration or scripting
To ask, just go to the repository and add an issue as a question. The goal isn't to stop awesome stuff, it's just to make sure there aren't conflicts or over complications.
Building docs locally¶
Building the documentation locally can be helpful to see the changes you are making and to verify there are no issues being introduced. However, this is not requred for doc contributions. However, this will be done as part of reviewing any pull requests that contain changes or additions to the documentation.
The PnP List Formatting repository uses MkDocs to build this documentation site. There is some initial setup required but you should only have to do it once.
Installing MkDocs and related plugins¶
Using a command prompt / terminal execute the following commands:
- Install MkDocs
pip install mkdocs
- Install the Material theme
pip install mkdocs-material
- Install the Markdown Extra Data plugin
pip install mkdocs-markdownextradata-plugin
Serving the documentation locally¶
Using a command prompt / terminal execute the following command:
Navigate to http://127.0.0.1:8000 in a browser to see the documentation. As you save documents you should see the pages refresh with your changes.