From 5f391fed966b95ea29429a4beb0efd458e05b276 Mon Sep 17 00:00:00 2001
From: gotbadger <p.j.h@hey.com>
Date: Thu, 2 Nov 2023 17:52:07 +0000
Subject: [PATCH] docs(ci): move to using stand alone ci examples

---
 docs/.eleventy.js                             |  31 +++
 docs/_data/examples/ci/circleci/basic.yaml    |  18 ++
 .../_data/examples/ci/circleci/reviewdog.yaml |  29 +++
 .../ci/github/basic-with-options.yaml         |  21 ++
 docs/_data/examples/ci/github/basic.yaml      |  17 ++
 docs/_data/examples/ci/github/cloud.yaml      |  17 ++
 .../_data/examples/ci/github/defect-dojo.yaml |  29 +++
 .../examples/ci/github/diff-reviewdog.yaml    |  30 +++
 docs/_data/examples/ci/github/diff.yaml       |  18 ++
 docs/_data/examples/ci/github/sarif.yaml      |  25 ++
 docs/_data/examples/ci/gitlab/basic.yaml      |   5 +
 docs/_data/examples/ci/gitlab/cloud.yaml      |   5 +
 .../examples/ci/gitlab/diff-reviewdog.yaml    |  10 +
 docs/_data/examples/ci/gitlab/diff.yaml       |   8 +
 docs/_data/examples/ci/gitlab/sast.yaml       |   9 +
 docs/_data/meta.js                            |   1 +
 docs/explanations/index.md                    |   6 +-
 docs/guides/bearer-cloud.md                   |  35 +--
 docs/guides/ci-setup.md                       |  75 +-----
 docs/guides/github-action.md                  |  76 ++++++
 docs/guides/github-action.njk                 | 244 ------------------
 docs/guides/gitlab.md                         |  65 +----
 docs/guides/index.md                          |   9 +-
 docs/reference/index.md                       |   8 +-
 24 files changed, 364 insertions(+), 427 deletions(-)
 create mode 100644 docs/_data/examples/ci/circleci/basic.yaml
 create mode 100644 docs/_data/examples/ci/circleci/reviewdog.yaml
 create mode 100644 docs/_data/examples/ci/github/basic-with-options.yaml
 create mode 100644 docs/_data/examples/ci/github/basic.yaml
 create mode 100644 docs/_data/examples/ci/github/cloud.yaml
 create mode 100644 docs/_data/examples/ci/github/defect-dojo.yaml
 create mode 100644 docs/_data/examples/ci/github/diff-reviewdog.yaml
 create mode 100644 docs/_data/examples/ci/github/diff.yaml
 create mode 100644 docs/_data/examples/ci/github/sarif.yaml
 create mode 100644 docs/_data/examples/ci/gitlab/basic.yaml
 create mode 100644 docs/_data/examples/ci/gitlab/cloud.yaml
 create mode 100644 docs/_data/examples/ci/gitlab/diff-reviewdog.yaml
 create mode 100644 docs/_data/examples/ci/gitlab/diff.yaml
 create mode 100644 docs/_data/examples/ci/gitlab/sast.yaml
 create mode 100644 docs/guides/github-action.md
 delete mode 100644 docs/guides/github-action.njk

diff --git a/docs/.eleventy.js b/docs/.eleventy.js
index 42c62bba7..1553593ff 100644
--- a/docs/.eleventy.js
+++ b/docs/.eleventy.js
@@ -12,7 +12,9 @@ const markdownItAnchor = require("markdown-it-anchor")
 const pluginTOC = require("eleventy-plugin-toc")
 const now = String(Date.now())
 const path = require("path")
+const fs = require("fs")
 const mermaid = require("./_src/_plugins/mermaid")
+const nav = require("./_data/nav")
 
 const mdSetup = markdownIt({ html: true })
   .use(markdownItEmoji)
@@ -48,6 +50,35 @@ module.exports = function (eleventyConfig) {
   eleventyConfig.addShortcode("version", function () {
     return now
   })
+  eleventyConfig.addShortcode("sectionLinks", function (sectionName) {
+    const section = nav.find(item => item.name == sectionName)
+    let out = ""
+    if(section){
+      section.items.forEach(item => {
+        out += `- [${item.name}](${item.url})\n`
+      })
+    }
+
+    return out
+  })
+
+  // {% yamlExample "ci/gitlab/basic" %}
+  eleventyConfig.addShortcode('yamlExample', function (exampleName) {
+    const example = fs.readFileSync(`./_data/examples/${exampleName}.yaml`, 'utf8')
+    return '```yaml\n' + example + '\n```';
+  });
+
+  eleventyConfig.addShortcode('githubAction', function(data){
+    out = "| Option | Description | Default |\n"
+    out += "| - | - | - |\n"
+    Object.keys(data).sort().forEach(key => {
+      const item = data[key]
+      const default_val = item.default ? "`"+item.default+"`" : ""
+      out += `| **${key}** | ${item.description} | ${default_val} |\n`
+    });
+    return out
+  })
+
   eleventyConfig.setLibrary("md", mdSetup)
   eleventyConfig.addPlugin(EleventyHtmlBasePlugin, {
     baseHref: "/",
diff --git a/docs/_data/examples/ci/circleci/basic.yaml b/docs/_data/examples/ci/circleci/basic.yaml
new file mode 100644
index 000000000..efeeb001a
--- /dev/null
+++ b/docs/_data/examples/ci/circleci/basic.yaml
@@ -0,0 +1,18 @@
+version: 2.1
+
+jobs:
+  bearer:
+    machine:
+      image: ubuntu-2204:2023.07.2
+    environment:
+      # Set to default branch of your repo
+      DEFAULT_BRANCH: main
+    steps:
+      - checkout
+      - run: curl -sfL https://raw.githubusercontent.com/Bearer/bearer/main/contrib/install.sh | sh -s -- -b /tmp
+      - run: CURRENT_BRANCH=$CIRCLE_BRANCH SHA=$CIRCLE_SHA1 /tmp/bearer scan .
+
+workflows:
+  test:
+    jobs:
+      - bearer
\ No newline at end of file
diff --git a/docs/_data/examples/ci/circleci/reviewdog.yaml b/docs/_data/examples/ci/circleci/reviewdog.yaml
new file mode 100644
index 000000000..174d9a840
--- /dev/null
+++ b/docs/_data/examples/ci/circleci/reviewdog.yaml
@@ -0,0 +1,29 @@
+version: 2.1
+
+jobs:
+  bearer:
+    machine:
+      image: ubuntu-2204:2023.07.2
+    environment:
+      # Set to default branch of your repo
+      DEFAULT_BRANCH: main
+    steps:
+      - checkout
+      - run: curl -sfL https://raw.githubusercontent.com/Bearer/bearer/main/contrib/install.sh | sh -s -- -b /tmp
+      - run: curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b /tmp
+      - run: |
+          CURRENT_BRANCH=$CIRCLE_BRANCH SHA=$CIRCLE_SHA1 /tmp/bearer scan . --format=rdjson --output=rd.json || export BEARER_EXIT=$?
+          cat rd.json | REVIEWDOG_GITHUB_API_TOKEN=$GITHUB_TOKEN /tmp/reviewdog -f=rdjson -reporter=github-pr-review
+          exit $BEARER_EXIT
+
+workflows:
+  test:
+    jobs:
+      - bearer:
+          filters:
+            branches:
+              # No need to run a check on default branch
+              ignore: main
+          context:
+            - bearer
+            # make sure to set GITHUB_TOKEN in your context
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/basic-with-options.yaml b/docs/_data/examples/ci/github/basic-with-options.yaml
new file mode 100644
index 000000000..ec2b4ff7a
--- /dev/null
+++ b/docs/_data/examples/ci/github/basic-with-options.yaml
@@ -0,0 +1,21 @@
+name: Bearer
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Bearer
+        uses: bearer/bearer-action@v2
+        with:
+          config-file: '/some/path/bearer.yml'
+          only-rule: 'ruby_lang_cookies,ruby_lang_http_post_insecure_with_data'
+          skip-path: 'users/*.go,users/admin.sql'
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/basic.yaml b/docs/_data/examples/ci/github/basic.yaml
new file mode 100644
index 000000000..6650a4cda
--- /dev/null
+++ b/docs/_data/examples/ci/github/basic.yaml
@@ -0,0 +1,17 @@
+name: Bearer
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Bearer
+        uses: bearer/bearer-action@v2
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/cloud.yaml b/docs/_data/examples/ci/github/cloud.yaml
new file mode 100644
index 000000000..7016b9110
--- /dev/null
+++ b/docs/_data/examples/ci/github/cloud.yaml
@@ -0,0 +1,17 @@
+name: Bearer
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run Report
+        id: report
+        uses: bearer/bearer-action@v2
+        with:
+          api-key: ${{ secrets.BEARER_TOKEN }}
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/defect-dojo.yaml b/docs/_data/examples/ci/github/defect-dojo.yaml
new file mode 100644
index 000000000..db5902dd9
--- /dev/null
+++ b/docs/_data/examples/ci/github/defect-dojo.yaml
@@ -0,0 +1,29 @@
+name: Bearer Defect Dojo
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run Report
+        id: report
+        uses: bearer/bearer-action@v2
+        with:
+          format: gitlab-sast
+          output: gl-sast-report.json
+      - name: Defect Dojo
+        if: always()
+        env:
+          DD_TOKEN: ${{ secrets.DD_TOKEN}}
+          DD_APP: ${{ secrets.DD_APP}}
+          DD_ENGAGEMENT: ${{ secrets.DD_ENGAGEMENT}}
+        run: |
+          curl -X POST -F "file=@gl-sast-report.json" -F "product_name=$DD_APP" -F "engagement_name=$DD_ENGAGEMENT" -F "scan_type=GitLab SAST Report" -H "Authorization: Token $DD_TOKEN" http://example.com/api/v2/import-scan/
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/diff-reviewdog.yaml b/docs/_data/examples/ci/github/diff-reviewdog.yaml
new file mode 100644
index 000000000..345567e51
--- /dev/null
+++ b/docs/_data/examples/ci/github/diff-reviewdog.yaml
@@ -0,0 +1,30 @@
+name: Bearer PR Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: reviewdog/action-setup@v1
+        with:
+          reviewdog_version: latest
+      - name: Bearer
+        uses: bearer/bearer-action@v2
+        with:
+          format: rdjson
+          output: rd.json
+          diff: true
+      - name: Run reviewdog
+        if: always()
+        env:
+          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cat rd.json | reviewdog -f=rdjson -reporter=github-pr-review
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/diff.yaml b/docs/_data/examples/ci/github/diff.yaml
new file mode 100644
index 000000000..c1e91c4a8
--- /dev/null
+++ b/docs/_data/examples/ci/github/diff.yaml
@@ -0,0 +1,18 @@
+name: Bearer PR Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Bearer
+        uses: bearer/bearer-action@v2
+        with:
+          diff: true
\ No newline at end of file
diff --git a/docs/_data/examples/ci/github/sarif.yaml b/docs/_data/examples/ci/github/sarif.yaml
new file mode 100644
index 000000000..5497265d4
--- /dev/null
+++ b/docs/_data/examples/ci/github/sarif.yaml
@@ -0,0 +1,25 @@
+name: Bearer
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  rule_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Bearer
+        uses: bearer/bearer-action@v2
+        with:
+          format: sarif
+          output: results.sarif
+      - name: Upload SARIF file
+        if: always()
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: results.sarif
\ No newline at end of file
diff --git a/docs/_data/examples/ci/gitlab/basic.yaml b/docs/_data/examples/ci/gitlab/basic.yaml
new file mode 100644
index 000000000..20c333d26
--- /dev/null
+++ b/docs/_data/examples/ci/gitlab/basic.yaml
@@ -0,0 +1,5 @@
+bearer:
+  image:
+    name: bearer/bearer
+    entrypoint: [ "" ]
+  script: bearer scan .
diff --git a/docs/_data/examples/ci/gitlab/cloud.yaml b/docs/_data/examples/ci/gitlab/cloud.yaml
new file mode 100644
index 000000000..650e6f091
--- /dev/null
+++ b/docs/_data/examples/ci/gitlab/cloud.yaml
@@ -0,0 +1,5 @@
+bearer:
+  image:
+    name: bearer/bearer
+    entrypoint: [ "" ]
+  script: bearer scan . --api-key=$BEARER_TOKEN
\ No newline at end of file
diff --git a/docs/_data/examples/ci/gitlab/diff-reviewdog.yaml b/docs/_data/examples/ci/gitlab/diff-reviewdog.yaml
new file mode 100644
index 000000000..1cf87b309
--- /dev/null
+++ b/docs/_data/examples/ci/gitlab/diff-reviewdog.yaml
@@ -0,0 +1,10 @@
+bearer_mr:
+  variables:
+    DIFF_BASE_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+    DIFF_BASE_COMMIT: $CI_MERGE_REQUEST_DIFF_BASE_SHA
+  script:
+    - curl -sfL https://raw.githubusercontent.com/Bearer/bearer/main/contrib/install.sh | sh -s -- -b /usr/local/bin
+    - curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b /usr/local/bin
+    - bearer scan . --format=rdjson --output=rd.json || export BEARER_EXIT=$?
+    - cat rd.json | reviewdog -f=rdjson -reporter=gitlab-mr-discussion
+    - exit $BEARER_EXIT
\ No newline at end of file
diff --git a/docs/_data/examples/ci/gitlab/diff.yaml b/docs/_data/examples/ci/gitlab/diff.yaml
new file mode 100644
index 000000000..1c95d02b4
--- /dev/null
+++ b/docs/_data/examples/ci/gitlab/diff.yaml
@@ -0,0 +1,8 @@
+bearer_mr:
+  image:
+    name: bearer/bearer
+    entrypoint: [ "" ]
+  variables:
+    DIFF_BASE_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+    DIFF_BASE_COMMIT: $CI_MERGE_REQUEST_DIFF_BASE_SHA
+  script: bearer scan .
\ No newline at end of file
diff --git a/docs/_data/examples/ci/gitlab/sast.yaml b/docs/_data/examples/ci/gitlab/sast.yaml
new file mode 100644
index 000000000..2595d627c
--- /dev/null
+++ b/docs/_data/examples/ci/gitlab/sast.yaml
@@ -0,0 +1,9 @@
+bearer:
+  image:
+    name: bearer/bearer
+    entrypoint: [ "" ]
+  script:
+    - bearer scan . --format gitlab-sast --output gl-sast-report.json
+  artifacts:
+    reports:
+      sast: gl-sast-report.json
\ No newline at end of file
diff --git a/docs/_data/meta.js b/docs/_data/meta.js
index 91b2bdb31..b968f8aa7 100644
--- a/docs/_data/meta.js
+++ b/docs/_data/meta.js
@@ -9,5 +9,6 @@ module.exports = {
   links: {
     discord: "https://discord.gg/eaHZBJUXRF",
     issues: "https://github.com/Bearer/bearer/issues",
+    action: "https://github.com/marketplace/actions/bearer-action"
   },
 };
diff --git a/docs/explanations/index.md b/docs/explanations/index.md
index d6140f58d..6c121b6a4 100644
--- a/docs/explanations/index.md
+++ b/docs/explanations/index.md
@@ -6,8 +6,4 @@ title: Explanations
 
 Explanations dive into the rational behind Bearer CLI and explain some of its heavier concepts.
 
-- [How Bearer CLI works](/explanations/workflow/)
-- [Sensitive data flow](/explanations/discovery-and-classification/)
-- [Report types](/explanations/reports/)
-- [Scanner Types](/explanations/scanners/)
-- [Dynamic Severity Levels](/explanations/severity/)
\ No newline at end of file
+{% sectionLinks "Explanations" %}
\ No newline at end of file
diff --git a/docs/guides/bearer-cloud.md b/docs/guides/bearer-cloud.md
index b72b703da..dc98f6041 100644
--- a/docs/guides/bearer-cloud.md
+++ b/docs/guides/bearer-cloud.md
@@ -49,26 +49,7 @@ bearer scan project-folder --api-key=XXXXXXXX
 
 Using the same setup process found in [the GitHub action guide](/guides/github-action/), configure the action to run `with` the `api-key` option. For example:
 
-```yaml
-# .github/workflows/bearer.yml
-name: Bearer
-on:
-  push:
-    branches:
-      - main
-permissions:
-  contents: read
-jobs:
-  rule_check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Run Report
-        id: report
-        uses: bearer/bearer-action@v2
-        with:
-          api-key: {% raw %}${{ secrets.BEARER_TOKEN }}{% endraw %}
-```
+{% yamlExample "ci/github/cloud" %}
 
 We highly recommend using GitHub's [encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets). In the example above, the secret is named `BEARER_TOKEN`.
 
@@ -76,19 +57,7 @@ We highly recommend using GitHub's [encrypted secrets](https://docs.github.com/e
 
 Set up the [GitLab CI/CD configuration](/guides/gitlab), then adjust your settings to include the `--api-key` flag with the `scan` command:
 
-```yaml
-# .gitlab-ci.yml
-bearer:
-  image:
-    name: bearer/bearer
-    entrypoint: [ "" ]
-  variables:
-    SHA: $CI_COMMIT_SHA
-    CURRENT_BRANCH: $CI_COMMIT_REF_NAME
-    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH
-    ORIGIN_URL: $CI_REPOSITORY_URL
-  script: bearer scan . --api-key=$BEARER_TOKEN
-```
+{% yamlExample "ci/gitlab/cloud" %}
 
 We recommend using [GitLab's CI/CD variables](https://docs.gitlab.com/ee/ci/variables/) to protect your token. In the example above, the variable is named `BEARER_TOKEN`.
 
diff --git a/docs/guides/ci-setup.md b/docs/guides/ci-setup.md
index 2e1f2e598..7a50a0576 100644
--- a/docs/guides/ci-setup.md
+++ b/docs/guides/ci-setup.md
@@ -8,13 +8,9 @@ Using Bearer CLI in your CI/CD pipeline works similarly to most other integratio
 
 ## GitHub
 
-Bearer offers an official [GitHub Action](https://github.com/marketplace/actions/bearer-security) to connect directly with your repository. To enable it with the default settings, create a `bearer.yml` file in your `.github/workflows` directory and include the following:
+Bearer offers an official [GitHub Action]({{meta.links.action}}) to connect directly with your repository. To enable it with the default settings, create a `bearer.yml` file in your `.github/workflows` directory and include the following:
 
-```yml
-steps:
-  - uses: actions/checkout@v3
-  - uses: bearer/bearer-action@v2
-```
+{% yamlExample "ci/github/basic" %}
 
 For more details and additional configuration, see our [guide to using the GitHub action](/guides/github-action/). To hook directly into GitHub's code scanning feature, check the [configure GitHub code scanning](/guides/github-action/#configure-github-code-scanning) section of the doc.
 
@@ -22,18 +18,7 @@ For more details and additional configuration, see our [guide to using the GitHu
 
 To integrate Bearer CLI with GitLab CI/CD, we recommend using the docker entrypoint method. Edit your existing `.gitlab-ci.yml` file or add one to your repository root, then add the following lines:
 
-```yml
-bearer:
-  image:
-    name: bearer/bearer
-    entrypoint: [ "" ]
-  variables:
-    SHA: $CI_COMMIT_SHA
-    CURRENT_BRANCH: $CI_COMMIT_REF_NAME
-    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH
-    ORIGIN_URL: $CI_REPOSITORY_URL
-  script: bearer scan .
-```
+{% yamlExample "ci/gitlab/basic" %}
 
 This tells GitLab to use the `bearer/bearer` docker image. You can adjust the `script` key to [customize the scan](/guides/configure-scan/) with flags the same way as a local installation. An example of this file is available in [our example GitLab repo](https://gitlab.com/bearer/bear-publishing/-/tree/main).
 
@@ -45,61 +30,11 @@ For more details and additional configuration, see our [guide to using GitLab](/
 
 To integrate with CircleCI, you can add the following job to your `.circleci/config.yml`
 
-```yml
-version: 2.1
-
-jobs:
-  bearer:
-    machine:
-      image: ubuntu-2204:2023.07.2
-    environment:
-      # Set to default branch of your repo
-      DEFAULT_BRANCH: main
-    steps:
-      - checkout
-      - run: curl -sfL https://raw.githubusercontent.com/Bearer/bearer/main/contrib/install.sh | sh -s -- -b /tmp
-      - run: CURRENT_BRANCH=$CIRCLE_BRANCH SHA=$CIRCLE_SHA1 /tmp/bearer scan .
-
-workflows:
-  test:
-    jobs:
-      - bearer
-```
+{% yamlExample "ci/circleci/basic" %}
 
 A more advanced example using a Github repository and reviewdog for PR comments:
 
-```yml
-version: 2.1
-
-jobs:
-  bearer:
-    machine:
-      image: ubuntu-2204:2023.07.2
-    environment:
-      # Set to default branch of your repo
-      DEFAULT_BRANCH: main
-    steps:
-      - checkout
-      - run: curl -sfL https://raw.githubusercontent.com/Bearer/bearer/main/contrib/install.sh | sh -s -- -b /tmp
-      - run: curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b /tmp
-      - run: |
-          CURRENT_BRANCH=$CIRCLE_BRANCH SHA=$CIRCLE_SHA1 /tmp/bearer scan . --format=rdjson --output=rd.json || export BEARER_EXIT=$?
-          cat rd.json | REVIEWDOG_GITHUB_API_TOKEN=$GITHUB_TOKEN /tmp/reviewdog -f=rdjson -reporter=github-pr-review
-          exit $BEARER_EXIT
-
-workflows:
-  test:
-    jobs:
-      - bearer:
-          filters:
-            branches:
-              # No need to run a check on default branch
-              ignore: main
-          context:
-            - bearer
-            # make sure to set GITHUB_TOKEN in your context
-
-```
+{% yamlExample "ci/circleci/reviewdog" %}
 
 The `GITHUB_TOKEN` in this case just requires read and write access to pull requests for the repository.
 
diff --git a/docs/guides/github-action.md b/docs/guides/github-action.md
new file mode 100644
index 000000000..b84e7708f
--- /dev/null
+++ b/docs/guides/github-action.md
@@ -0,0 +1,76 @@
+---
+title: Using GitHub Action
+---
+
+# Using GitHub Action
+
+Running Bearer from the CLI is great, but if you want it integrated directly with your Git workflow there's nothing easier than a GitHub action. If you're unfamiliar with GitHub actions, here's a [primer available from GitHub](https://github.com/features/actions). You can also see how the action works directly on our [Bear Publishing example app](https://github.com/Bearer/bear-publishing/actions/workflows/bearer.yml).
+
+## Getting started
+
+You can [view the action here]({{meta.links.action}}), or follow along below.
+
+Actions live in the `.github/workflows/` directory within your repository. Start by creating a `bearer.yml` file in the workflows directory.
+
+We recommend the following config in `.github/workflows/bearer.yml` to run Bearer's security report:
+
+{% yamlExample "ci/github/basic" %}
+
+This will run the [security report](/explanations/reports), show the report in the job log, and flag the action as pass or fail based on whether Bearer's default rules pass or fail.
+
+## Further configuration
+
+Just as with the CLI app, you can configure the action to meet the needs of your project. Set custom inputs and outputs using the `with` key. Here's an example using the `config-file`, `skip-path`, and `only-rule` flags:
+
+{% yamlExample "ci/github/basic-with-options" %}
+
+### Inputs
+
+{% githubAction bearerAction.inputs %}
+
+### Outputs
+If you want to process the output of the cli we recommend using the `output` input above to write a file that can be used elsewhere, but we also provide some basic outputs you can use if needed:
+
+{% githubAction bearerAction.outputs %}
+
+## Configure GitHub code scanning
+Bearer CLI supports [GitHub code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning). By using the SARIF output format, you can display [security report](/explanations/reports/#security-report) findings directly in the Security tab of your repository.
+
+![Bearer CLI results in GitHub security tab](/assets/img/gh-code-scanning.jpg)
+
+To enable this feature, update your action configuration to include new permissions, new format and outputs, and an additional step. Here's an example configuration:
+
+{% yamlExample "ci/github/sarif" %}
+
+By setting the format and output path, and adding a new upload step, the action will upload SARIF-formatted findings to GitHub's code scanner.
+
+## Pull Request Diff
+
+When the Bearer action is being used to check a pull request, you can tell the
+action to only report findings introduced within the pull request by setting
+the `diff` input parameter to `true`.
+
+{% yamlExample "ci/github/diff" %}
+
+See our guide on [configuring a scan](/guides/configure-scan#only-report-new-findings-on-a-branch)
+for more information on differential scans.
+
+## Code Review Comments
+Bearer CLI supports [Reviewdog](https://github.com/reviewdog/reviewdog) rdjson format so you can use any of the reviewdog reporters to quickly add bearer feedback directly to your pull requests.
+
+![Bearer CLI results in Github PR](/assets/img/gh-pr-review.png)
+
+{% yamlExample "ci/github/diff-reviewdog" %}
+
+## Integrate with Defect Dojo
+
+We can monitor findings with [Defect Dojo](https://github.com/DefectDojo/django-DefectDojo) by using the `gitlab-sast` format and the v2 API. Make sure to update the instance url and set the necessary secrets.
+
+{% yamlExample "ci/github/defect-dojo" %}
+
+## Make the most of Bearer
+
+For more ways to use Bearer, check out the different [report types](/explanations/reports/), [available rules](/reference/rules/), [supported data types](/reference/datatypes/).
+
+Have a question or need help? Join our [Discord community](https://discord.gg/eaHZBJUXRF) or [open an issue on GitHub](https://github.com/Bearer/bearer/issues).
+
diff --git a/docs/guides/github-action.njk b/docs/guides/github-action.njk
deleted file mode 100644
index e2c2ceb23..000000000
--- a/docs/guides/github-action.njk
+++ /dev/null
@@ -1,244 +0,0 @@
----
-title: Using GitHub Action
----
-{% renderTemplate "md" %}
-
-# Using GitHub Action
-
-Running Bearer from the CLI is great, but if you want it integrated directly with your Git workflow there's nothing easier than a GitHub action. If you're unfamiliar with GitHub actions, here's a [primer available from GitHub](https://github.com/features/actions). You can also see how the action works directly on our [Bear Publishing example app](https://github.com/Bearer/bear-publishing/actions/workflows/bearer.yml).
-
-## Getting started
-
-You can [view the action here](https://github.com/marketplace/actions/bearer-security), or follow along below.
-
-Actions live in the `.github/workflows/` directory within your repository. Start by creating a `bearer.yml` file in the workflows directory.
-
-We recommend the following config in `.github/workflows/bearer.yml` to run Bearer's security report:
-
-```yaml
-name: Bearer
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: read
-
-jobs:
-  rule_check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Run Report
-        id: report
-        uses: bearer/bearer-action@v2
-```
-
-This will run the [security report](/explanations/reports), display the results to the action summary screen within GitHub, and flag the action as pass or fail based on whether Bearer's default rules pass or fail.
-
-## Further configuration
-
-Just as with the CLI app, you can configure the action to meet the needs of your project. Set custom inputs and outputs using the `with` key. Here's an example using the `config-file`, `skip-path`, and `only-rule` flags:
-
-```yaml
-steps:
-  - uses: actions/checkout@v3
-  - name: Bearer
-    uses: bearer/bearer-action@v2
-    with:
-      config-file: '/some/path/bearer.yml'
-      only-rule: 'ruby_lang_cookies,ruby_lang_http_post_insecure_with_data'
-      skip-path: 'users/*.go,users/admin.sql'
-```
-
-The following are a list of available inputs and outputs:
-{% endrenderTemplate %}
-
-<h3>Inputs</h3>
-
-{% for key, value in bearerAction.inputs %}
-  <h4>
-    <code class="language-">{{key}}</code>
-  </h4>
-  <p>{{value.description}}
-    {% if not value.required %}
-      <strong>(Optional)</strong>
-    {% endif %}
-  </p>
-{% endfor %}
-
-<h3>Outputs</h3>
-{% for key, value in bearerAction.outputs %}
-  <h4>
-    <code class="language-">{{key}}</code>
-  </h4>
-  <p>{{value.description}}
-    {% if not value.required %}
-      <strong>(Optional)</strong>
-    {% endif %}
-  </p>
-{% endfor %}
-
-{% renderTemplate "md" %}
-## Configure GitHub code scanning
-Bearer CLI supports [GitHub code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning). By using the SARIF output format, you can display [security report](/explanations/reports/#security-report) findings directly in the Security tab of your repository.
-
-![Bearer CLI results in GitHub security tab](/assets/img/gh-code-scanning.jpg)
-
-To enable this feature, update your action configuration to include new permissions, new format and outputs, and an additional step. Here's an example configuration:
-
-```diff-yaml
-name: Bearer
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: read
-+ # Add the security-events permission
-  security-events: write
-
-jobs:
-  rule_check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Run Report
-        id: report
-        uses: bearer/bearer-action@v2
-        with:
-+         # Include these two options
-          format: sarif
-          output: results.sarif
-+       # Add a new step to upload the SARIF file
-      - name: Upload SARIF file
-        if: always()
-        uses: github/codeql-action/upload-sarif@v2
-        with:
-          sarif_file: results.sarif
-```
-
-By setting the format and output path, and adding a new upload step, the action will upload SARIF-formatted findings to GitHub's code scanner.
-
-## Pull Request Diff
-
-When the Bearer action is being used to check a pull request, you can tell the
-action to only report findings introduced within the pull request by setting
-the `diff` input parameter to `true`.
-
-```diff-yaml
-name: Bearer PR Check
-
-on:
-+ # Diff can only be used with pull_request events
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  contents: read
-
-jobs:
-  rule_check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Run Report
-        id: report
-        uses: bearer/bearer-action@v2
-        with:
-+         # Add diff option
-          diff: true
-```
-
-See our guide on [configuring a scan](/guides/configure-scan#only-report-new-findings-on-a-branch)
-for more information on differential scans.
-
-## Code Review Comments
-Bearer CLI supports [Reviewdog](https://github.com/reviewdog/reviewdog) rdjson format so you can use any of the reviewdog reporters to quickly add bearer feedback directly to your pull requests.
-
-![Bearer CLI results in Github PR](/assets/img/gh-pr-review.png)
-
-```diff-yaml
-name: Bearer PR Check
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  contents: read
-+ # Add the pull-requests permission
-  pull-requests: write
-
-jobs:
-  rule_check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-+     # install reviewdog
-      - uses: reviewdog/action-setup@v1
-        with:
-          reviewdog_version: latest
-      - name: Run Report
-        id: report
-        uses: bearer/bearer-action@v2
-        with:
-+         # use rdjson output, and only report changes from your PR
-          format: rdjson
-          output: rd.json
-          diff: true
-+     # always run reviewdog otherwise the step will be skiped by github when a scan fails
-      - name: Run reviewdog
-        if: always()
-        env:
-          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          cat rd.json | reviewdog -f=rdjson -reporter=github-pr-review
-```
-
-## Integrate with Defect Dojo
-
-We can monitor findings with [Defect Dojo](https://github.com/DefectDojo/django-DefectDojo) by using the `gitlab-sast` format and the v2 API. Make sure to update the instance url and set the necessary secrets.
-
-```yaml
-name: Bearer Defect Dojo
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: read
-
-jobs:
-  rule_check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Run Report
-        id: report
-        uses: bearer/bearer-action@v2
-        with:
-          format: gitlab-sast
-          output: gl-sast-report.json
-      - name: Defect Dojo
-        if: always()
-        env:
-          DD_TOKEN: ${{ secrets.DD_TOKEN}}
-          DD_APP: ${{ secrets.DD_APP}}
-          DD_ENGAGEMENT: ${{ secrets.DD_ENGAGEMENT}}
-        run: |
-          curl -X POST -F "file=@gl-sast-report.json" -F "product_name=$DD_APP" -F "engagement_name=$DD_ENGAGEMENT" -F "scan_type=GitLab SAST Report" -H "Authorization: Token $DD_TOKEN" http://example.com/api/v2/import-scan/
-```
-
-## Make the most of Bearer
-
-For more ways to use Bearer, check out the different [report types](/explanations/reports/), [available rules](/reference/rules/), [supported data types](/reference/datatypes/).
-
-Have a question or need help? Join our [Discord community](https://discord.gg/eaHZBJUXRF) or [open an issue on GitHub](https://github.com/Bearer/bearer/issues).
-{% endrenderTemplate %}
diff --git a/docs/guides/gitlab.md b/docs/guides/gitlab.md
index 32fc8a24d..e7990b8a0 100644
--- a/docs/guides/gitlab.md
+++ b/docs/guides/gitlab.md
@@ -1,7 +1,6 @@
 ---
 title: Using GitLab CI/CD
 ---
-{% renderTemplate "md" %}
 
 # Using GitLab CI/CD
 
@@ -12,18 +11,7 @@ Running Bearer from the CLI is great, but if you want it integrated directly wit
 
 To integrate Bearer CLI with GitLab CI/CD, we recommend using the docker entrypoint method. Edit your existing `.gitlab-ci.yml` file or add one to your repository root, then add the following lines:
 
-```yml
-bearer:
-  image:
-    name: bearer/bearer
-    entrypoint: [ "" ]
-  variables:
-    SHA: $CI_COMMIT_SHA
-    CURRENT_BRANCH: $CI_COMMIT_REF_NAME
-    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH
-    ORIGIN_URL: $CI_REPOSITORY_URL
-  script: bearer scan .
-```
+{% yamlExample "ci/gitlab/basic" %}
 
 This tells GitLab to use the `bearer/bearer` docker image. You can adjust the `script` key to [customize the scan](/guides/configure-scan/) with flags the same way as a local installation. An example of this file is available in [our example GitLab repo](https://gitlab.com/bearer/bear-publishing/-/tree/main).
 
@@ -37,23 +25,7 @@ GitLab offers an integrated security scanner that can take results from Bearer C
 
 To take advantage of this, you'll need a GitLab plan that supports it. Then, you can configure your `.gitlab-ci.yml` file with Bearer CLI's special format type.
 
-```yml
-bearer:
-  image:
-    name: bearer/bearer
-    entrypoint: [ "" ]
-  variables:
-    SHA: $CI_COMMIT_SHA
-    CURRENT_BRANCH: $CI_COMMIT_REF_NAME
-    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH
-    ORIGIN_URL: $CI_REPOSITORY_URL
-  script:
-    - bearer scan . --format gitlab-sast --output gl-sast-report.json
-
-  artifacts:
-    reports:
-      sast: gl-sast-report.json
-```
+{% yamlExample "ci/gitlab/sast" %}
 
 These changes set the format to `gitlab-sast` and write an artifact that GitLab can use. Once run, the results of the security scan will display in the Security and Compliance section of the repository.
 
@@ -63,20 +35,7 @@ When Bearer CLI is being used to check a merge request, you can tell the Bearer
 CLI to only report findings introduced within the merge request by setting the
 `DIFF_BASE_BRANCH` variable.
 
-```yml
-bearer:
-  image:
-    name: bearer/bearer
-    entrypoint: [ "" ]
-  variables:
-    SHA: $CI_COMMIT_SHA
-    CURRENT_BRANCH: $CI_COMMIT_REF_NAME
-    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH
-    ORIGIN_URL: $CI_REPOSITORY_URL
-    DIFF_BASE_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
-    DIFF_BASE_COMMIT: $CI_MERGE_REQUEST_DIFF_BASE_SHA
-  script: bearer scan .
-```
+{% yamlExample "ci/gitlab/diff" %}
 
 See our guide on [configuring a scan](/guides/configure-scan#only-report-new-findings-on-a-branch)
 for more information on differential scans.
@@ -89,21 +48,7 @@ Bearer CLI supports [Reviewdog](https://github.com/reviewdog/reviewdog) rdjson f
 
 To keep the thing in one job we download each binary then run the two commands individually.
 
-```yml
-pr_check:
-  variables:
-    SHA: $CI_COMMIT_SHA
-    CURRENT_BRANCH: $CI_COMMIT_REF_NAME
-    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH
-    ORIGIN_URL: $CI_REPOSITORY_URL
-    DIFF_BASE_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
-    DIFF_BASE_COMMIT: $CI_MERGE_REQUEST_DIFF_BASE_SHA
-  script:
-    - curl -sfL https://raw.githubusercontent.com/Bearer/bearer/main/contrib/install.sh | sh -s -- -b /usr/local/bin
-    - curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b /usr/local/bin
-    - bearer scan . --format=rdjson --output=rd.json
-    - cat rd.json | reviewdog -f=rdjson -reporter=gitlab-mr-discussion
-```
+{% yamlExample "ci/gitlab/diff-reviewdog" %}
 
 [Don't forget](https://github.com/reviewdog/reviewdog#reporter-gitlab-mergerequest-discussions--reportergitlab-mr-discussion) to set `REVIEWDOG_GITLAB_API_TOKEN` in your project environment variables with a personal API access token.
 
@@ -112,4 +57,4 @@ pr_check:
 For more ways to use Bearer, check out the different [report types](/explanations/reports/), [available rules](/reference/rules/), [supported data types](/reference/datatypes/).
 
 Have a question or need help? Join our [Discord community](https://discord.gg/eaHZBJUXRF) or [open an issue on GitHub](https://github.com/Bearer/bearer/issues).
-{% endrenderTemplate %}
+
diff --git a/docs/guides/index.md b/docs/guides/index.md
index 3d55cfaec..bc01ca5d3 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -6,11 +6,4 @@ title: Guides
 
 Guides help you make the most of Bearer CLI so you can get up and running quickly. Have a request for a new guide? Open an [issue on GitHub]({{meta.links.issues}}).
 
-- [Configure the scan command](/guides/configure-scan/)
-- [Using GitHub action](/guides/github-action/)
-- [Using GitLab CI/CD](/guides/gitlab/)
-- [Set up CI/CD](/guides/ci-setup/)
-- [Create a custom rule](/guides/custom-rule/)
-- [Run a privacy report](/guides/privacy/)
-- [Run a data flow report](/guides/dataflow/)
-- [Using Bearer Cloud](/guides/bearer-cloud/)
\ No newline at end of file
+{% sectionLinks "Guides" %}
\ No newline at end of file
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 7811db92c..ef1819f95 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -6,10 +6,4 @@ title: Reference
 
 Reference documents are where you'll find detailed information about each command, as well as support charges for languages, rules, datatypes, and more.
 
-- [Built-in Rules](/reference/rules/)
-- [Supported Data Types](/reference/datatypes/)
-- [Recipes](/reference/recipes/)
-- [Commands](/reference/commands/)
-- [Supported Languages](/reference/supported-languages/)
-- [Configuration](/reference/config/)
-- [Installation](/reference/installation/)
\ No newline at end of file
+{% sectionLinks "Reference" %}
\ No newline at end of file