Format and lint all docs

docs/.markdownlint.json

@@ -20,7 +20,6 @@
     "tables": false
   },
   "no-bare-urls": false,
-  "no-duplicate-heading": false,
   "proper-names": {
     "code_blocks": false,
     "names": ["GitHub", "GitLab", "Bitbucket"]

docs/README.md

@@ -3,8 +3,8 @@
 This directory contains the user documentation for Minder, hosted at
 <https://mindersec.github.io>.
 
-The docs are built with [Docusaurus](<[https://](https://docusaurus.io/)>), an
-open source static website generator optimized for documentation use cases.
+The docs are built with [Docusaurus](https://docusaurus.io/), an open source
+static website generator optimized for documentation use cases.
 
 ## Contributing to docs
 
@@ -24,28 +24,34 @@ CLI docs:
 make cli-docs
 ```
 
-Run a preview server:
+Change to the docs directory:
+
+```bash
+cd docs
+```
+
+Run a preview server (this will automatically refresh most changes as you make
+them):
 
 ```bash
 npm run start
 ```
 
 Your browser should automatically open to <http://localhost:3000>
 
-Build the docs:
+Run a "production" build, this will also test for broken internal links:
 
 ```bash
-cd docs
 npm run build
 ```
 
-Serve the docs
+Serve the production build locally:
 
 ```bash
 npm run serve -- --port 3001
 ```
 
-Visit http://localhost:3001/ to view the docs.
+Visit http://localhost:3001/ to view the build.
 
 ## Formatting
 

docs/docs/about/_category_.yml

@@ -1,2 +1,2 @@
 label: About Minder
-position: 100
+position: 100

docs/docs/about/changelog.md

@@ -3,39 +3,51 @@ title: Changelog
 sidebar_position: 30
 ---
 
-# Changelog
-
-* **Profile selectors** - Sep 9, 2024  
-    You can now specify which repositories a profile applies to using a Common Expression Language (CEL) grammar.
-
-* **Rule evaluation history** - Sep 4, 2024  
-    You can now see how your security rules have applied to your repositories, pull requests, and artifacts throughout time, in addition to their current state.
-
-* **User management** - Aug 5, 2024  
-    Minder organization administrators can now invite additional users to the organization, and can set users permissions.
-
-* **Manage all GitHub repositories** - Jul 17, 2024  
-    Minder can now (optionally) manage all repositories within a GitHub organization, including new repositories that are created. Administrators can continue to select individual repositories to manage.
-
-* **Built-in rules** - Apr 6, 2024  
-    Minder now includes all the rules in our [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles/) in your new projects automatically. This means that you do not need to clone that repository or add those rule types to make use of them.
-
-    To use them, prefix the rule name as it exists in the sample rules repository with `stacklok/`. For example:
-
-    ```yaml
-    ---
-    version: v1
-    type: profile
-    name: uses-builtin-rules
-    context:
-      provider: github
-    repository:
+- **Profile selectors** - Sep 9, 2024  
+   You can now specify which repositories a profile applies to using a Common
+  Expression Language (CEL) grammar.
+
+- **Rule evaluation history** - Sep 4, 2024  
+   You can now see how your security rules have applied to your repositories,
+  pull requests, and artifacts throughout time, in addition to their current
+  state.
+
+- **User management** - Aug 5, 2024  
+   Minder organization administrators can now invite additional users to the
+  organization, and can set users permissions.
+
+- **Manage all GitHub repositories** - Jul 17, 2024  
+   Minder can now (optionally) manage all repositories within a GitHub
+  organization, including new repositories that are created. Administrators can
+  continue to select individual repositories to manage.
+
+- **Built-in rules** - Apr 6, 2024  
+   Minder now includes all the rules in our
+  [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles/)
+  in your new projects automatically. This means that you do not need to clone
+  that repository or add those rule types to make use of them.
+
+  To use them, prefix the rule name as it exists in the sample rules repository
+  with `stacklok/`. For example:
+
+  ```yaml
+  ---
+  version: v1
+  type: profile
+  name: uses-builtin-rules
+  context:
+    provider: github
+  repository:
     - type: stacklok/secret_scanning
       def:
         enabled: true
-    ```
+  ```
 
-    You can still define custom rules, or continue to use the rules that exist in the [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles).
+  You can still define custom rules, or continue to use the rules that exist in
+  the
+  [sample rules repository](https://github.com/mindersec/minder-rules-and-profiles).
 
-* **User roles** - Jan 30, 2024  
-  You can now provide access control for users (eg: administrator, editor, viewer) in your project using [built-in roles](../user_management/user_roles.md).
+- **User roles** - Jan 30, 2024  
+  You can now provide access control for users (eg: administrator, editor,
+  viewer) in your project using
+  [built-in roles](../user_management/user_roles.md).

docs/docs/about/contributing.md

@@ -3,18 +3,34 @@ title: Contributing to Minder
 sidebar_position: 80
 ---
 
-# Contributing to Minder
-Minder is an open-source project, and we welcome contributions from the community. There are several ways to contribute to Minder, including reporting bugs, suggesting new features, and submitting pull requests with code changes.
+Minder is an open-source project, and we welcome contributions from the
+community. There are several ways to contribute to Minder, including reporting
+bugs, suggesting new features, and submitting pull requests with code changes.
 
-## Reporting Security Vulnerabilities
-If you think you have found a security vulnerability in Minder please DO NOT disclose it publicly until we’ve had a chance to fix it. Please don’t report security vulnerabilities using GitHub issues; instead, please follow this [process](https://github.com/mindersec/minder/blob/main/SECURITY.md).
+## Reporting security vulnerabilities
+
+If you think you have found a security vulnerability in Minder please DO NOT
+disclose it publicly until we've had a chance to fix it. Please don't report
+security vulnerabilities using GitHub issues; instead, please follow this
+[process](https://github.com/mindersec/minder/blob/main/SECURITY.md).
 
 ## Creating GitHub issues
-GitHub issues are used to track feature request and bug reports. If you have a general usage question, please ask in [Minder's discussion forum](https://discord.com/invite/RkzVuTp3WK). If you are reporting a bug or requesting a feature, you can create a new issue in the [Minder GitHub repository](https://github.com/mindersec/minder/issues).
+
+GitHub issues are used to track feature request and bug reports. If you have a
+general usage question, please ask in
+[Minder's discussion forum](https://discord.com/invite/RkzVuTp3WK). If you are
+reporting a bug or requesting a feature, you can create a new issue in the
+[Minder GitHub repository](https://github.com/mindersec/minder/issues).
 
 ## Contributing code
-If you've found an issue you'd like to work on, you can contribute code to Minder by submitting a pull request. Before you submit a pull request, please review the [Pull request process](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md#pull-request-process).
+
+If you've found an issue you'd like to work on, you can contribute code to
+Minder by submitting a pull request. Before you submit a pull request, please
+review the
+[Pull request process](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md#pull-request-process).
 
 Thank you for taking the time to contribute to Minder!
 
-The full guide to contributing is available in our [Contributor Guidelines](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md) in the Minder open-source repository.
+The full guide to contributing is available in our
+[Contributor Guidelines](https://github.com/mindersec/minder/blob/main/CONTRIBUTING.md)
+in the Minder open-source repository.

docs/docs/about/roadmap.md

@@ -3,39 +3,78 @@ title: Roadmap
 sidebar_position: 70
 ---
 
-# Roadmap
 ## About this roadmap
 
-This roadmap should serve as a reference point for Minder users and community members to understand where the project is heading. The roadmap is where you can learn about what features we're working on, what stage they're in, and when we expect to bring them to you. Priorities and requirements may change based on community feedback, roadblocks encountered, community contributions, and other factors. If you depend on a specific item, we encourage you to reach out to Stacklok to get updated status information, or help us deliver that feature by contributing to Minder.
+This roadmap should serve as a reference point for Minder users and community
+members to understand where the project is heading. The roadmap is where you can
+learn about what features we're working on, what stage they're in, and when we
+expect to bring them to you. Priorities and requirements may change based on
+community feedback, roadblocks encountered, community contributions, and other
+factors. If you depend on a specific item, we encourage you to reach out to
+Stacklok to get updated status information, or help us deliver that feature by
+contributing to Minder.
 
 ## How to contribute
 
-Have any questions or comments about items on the Minder roadmap? Share your feedback via [Minder GitHub Discussions](https://github.com/mindersec/minder/discussions). 
+Have any questions or comments about items on the Minder roadmap? Share your
+feedback via
+[Minder GitHub Discussions](https://github.com/mindersec/minder/discussions).
 
-_Last updated: June 2024_
+**Last updated:** June 2024
 
 ## In progress
 
-* **Improved information about alerts:** Improve the verbiage and explanation about the state of rule evaluations, and how you can remediate the problems. 
-* **Enforce license information for dependencies:** Ensure that dependencies in your repositories use licenses that you approve.
-* **Create policy to manage licenses in PRs:** Add a rule type to block and/or add comments to pull requests based on the licenses of the dependencies they import.
-* **Generalized "provider" support:** Improve the ability for developers to add integration points to Minder to provide custom information about entities in their software development lifecycle.
+- **Improved information about alerts:** Improve the verbiage and explanation
+  about the state of rule evaluations, and how you can remediate the problems.
+- **Enforce license information for dependencies:** Ensure that dependencies in
+  your repositories use licenses that you approve.
+- **Create policy to manage licenses in PRs:** Add a rule type to block and/or
+  add comments to pull requests based on the licenses of the dependencies they
+  import.
+- **Generalized "provider" support:** Improve the ability for developers to add
+  integration points to Minder to provide custom information about entities in
+  their software development lifecycle.
 
 ## Next
 
-* **Report CVEs, Stacklok Insight scores, and license info for ingested SBOMs:** Ingest SBOMS and identify dependencies; show CVEs, Stacklok Insight scores, and license information including any changes over time.
-* **Block PRs based on Stacklok Insight scores:** In addition to adding comments to pull requests (as is currently available), add the option to block pull requests as a policy remediation.
-* **Policy events:** Provide information about rule evaluation as it changes, and historical rule evaluation.
-* **Generate SBOMs:** Enable users to automatically create and sign SBOMs.
+- **Report CVEs, Stacklok Insight scores, and license info for ingested SBOMs:**
+  Ingest SBOMS and identify dependencies; show CVEs, Stacklok Insight scores,
+  and license information including any changes over time.
+- **Block PRs based on Stacklok Insight scores:** In addition to adding comments
+  to pull requests (as is currently available), add the option to block pull
+  requests as a policy remediation.
+- **Policy events:** Provide information about rule evaluation as it changes,
+  and historical rule evaluation.
+- **Generate SBOMs:** Enable users to automatically create and sign SBOMs.
 
 ## Future considerations
 
-* **Project hierarchies:** Enable users to create nested projects and group repositories within those projects. Projects will inherit profile rules in order to simplify profile and policy management.
-* **Automate the generation and signing of SLSA provenance statements:** Enable users to generate SLSA provenance statements (e.g. through SLSA GitHub generator) and sign them with Sigstore.
-* **Register GitLab and Bitbucket repositories:** In addition to managing GitHub repositories, enable users to manage configuration and policy for other source control providers.
-* **Export a Minder 'badge/certification' that shows what practices a project followed:** Create a badge that OSS maintainers and enterprise developers can create and share with others that asserts the Minder practices and policies their projects follow.
-* **Temporary permissions to providers vs. long-running:** Policy remediation currently requires long-running permissions to providers such as GitHub; provide the option to enable temporary permissions.
-* **Create PRs for dependency updates:** As a policy autoremediation option, enable Minder to automatically create pull requests to update dependencies based on vulnerabilities, Stacklok Insight scores, or license changes.
-* **Drive policy through git (config management):** Enable users to dynamically create and maintain policies from other sources, e.g. Git, allowing for easier policy maintenance and the ability to manage policies through GitOps workflows.
-* **Integrations with additional OSS and commercial tools:** Integrate with tools that run code and secrets scanning (eg Snyk), and behavior analysis (eg [OSSF Package Analysis tool](https://github.com/ossf/package-analysis)).
-* **Help package authors improve Stacklok Insight Scores:** Provide guidance and/or policy to improve key Stacklok Insight Store metrics (open issues, active contributors).
+- **Project hierarchies:** Enable users to create nested projects and group
+  repositories within those projects. Projects will inherit profile rules in
+  order to simplify profile and policy management.
+- **Automate the generation and signing of SLSA provenance statements:** Enable
+  users to generate SLSA provenance statements (e.g. through SLSA GitHub
+  generator) and sign them with Sigstore.
+- **Register GitLab and Bitbucket repositories:** In addition to managing GitHub
+  repositories, enable users to manage configuration and policy for other source
+  control providers.
+- **Export a Minder 'badge/certification' that shows what practices a project
+  followed:** Create a badge that OSS maintainers and enterprise developers can
+  create and share with others that asserts the Minder practices and policies
+  their projects follow.
+- **Temporary permissions to providers vs. long-running:** Policy remediation
+  currently requires long-running permissions to providers such as GitHub;
+  provide the option to enable temporary permissions.
+- **Create PRs for dependency updates:** As a policy autoremediation option,
+  enable Minder to automatically create pull requests to update dependencies
+  based on vulnerabilities, Stacklok Insight scores, or license changes.
+- **Drive policy through git (config management):** Enable users to dynamically
+  create and maintain policies from other sources, e.g. Git, allowing for easier
+  policy maintenance and the ability to manage policies through GitOps
+  workflows.
+- **Integrations with additional OSS and commercial tools:** Integrate with
+  tools that run code and secrets scanning (eg Snyk), and behavior analysis (eg
+  [OSSF Package Analysis tool](https://github.com/ossf/package-analysis)).
+- **Help package authors improve Stacklok Insight Scores:** Provide guidance
+  and/or policy to improve key Stacklok Insight Store metrics (open issues,
+  active contributors).

docs/docs/developer_guide/_category_.yml

@@ -1,2 +1,2 @@
-label: Developer Guide
-position: 50
+label: Developer guide
+position: 50