Docs/docusaurus 3 (#5)

* initial commit for docusaurus 3 upgrade

* fix mdx errors

* fix mdx issues

* fix routing issues

* update docs generation workflow

* fix version

* fix permissions

* move slack to header

* remove background color and minify

* Add suggestions

Author: tuunit

.github/workflows/docs.yaml

@@ -7,66 +7,62 @@ on:
   push:
     branches: [master]
     paths: ['docs/**']
+  workflow_dispatch:
 
 jobs:
   pull-request-check:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
 
       - uses: actions/setup-node@v3
         with:
-          node-version: 18
+          node-version: 20
+          cache: npm
+          cache-dependency-path: "./docs/package-lock.json"
 
       - name: Test Build
         working-directory: ./docs
         run: |
           npm ci
           npm run build
 
-  gh-pages-release:
-    if: github.event_name == 'push'
+  build-docs:
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
       - uses: actions/checkout@v4
-        with:
-          path: master
-      
-      - uses: actions/checkout@v4
-        with:
-          ref: gh-pages
-          path: gh-pages
 
       - uses: actions/setup-node@v3
         with:
-          node-version: 18
+          node-version: 20
 
       - name: Build docusaurus
-        working-directory: master/docs
-        id: build
+        working-directory: ./docs
         run: |
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
           npm ci
           npm run build
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
 
-      - name: Release to github pages
-        env:
-          GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        working-directory: gh-pages
-        run: |
-          git config --local user.name "github-actions[bot]"
-          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
-          # Remove all files except .git
-          git rm -r *
-
-          # Copy the build files from master/docs/build to gh-pages
-          cp -r ../master/docs/build/* .
-
-          # Commit and push
-          git add .
-          git commit -m "Update documentation based on ${{ steps.build.outputs.sha }}"
-          git push origin gh-pages
+  deploy-docs:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/docs/configuration/overview.md

@@ -85,7 +85,7 @@ An example [oauth2-proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/
 | `--cookie-httponly` | bool | set HttpOnly cookie flag | true |
 | `--cookie-name` | string | the name of the cookie that the oauth_proxy creates. Should be changed to use a [cookie prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes) (`__Host-` or `__Secure-`) if `--cookie-secure` is set. | `"_oauth2_proxy"` |
 | `--cookie-path` | string | an optional cookie path to force cookies to (e.g. `/poc/`) | `"/"` |
-| `--cookie-refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers \[[1](#footnote1)\] | |
+| `--cookie-refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers [^1] | |
 | `--cookie-secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
 | `--cookie-secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
 | `--cookie-samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
@@ -175,7 +175,7 @@ An example [oauth2-proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/
 | `--request-logging` | bool | Log requests | true |
 | `--request-logging-format` | string | Template for request log lines | see [Logging Configuration](#logging-configuration) |
 | `--resource` | string | The resource that is protected (Azure AD only) | |
-| `--reverse-proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted and allows X-Forwarded-{Proto,Host,Uri} headers to be used on redirect selection | false |
+| `--reverse-proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted and allows X-Forwarded-\{Proto,Host,Uri\} headers to be used on redirect selection | false |
 | `--scope` | string | OAuth scope specification | |
 | `--session-cookie-minimal` | bool | strip OAuth tokens from cookie session stores if they aren't needed (cookie session store only) | false |
 | `--session-store-type` | string | [Session data storage backend](sessions.md); redis or cookie | cookie |
@@ -206,12 +206,12 @@ An example [oauth2-proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/
 | `--allowed-role` | string \| list | restrict logins to users with this role (may be given multiple times). Only works with the keycloak-oidc provider. | |
 | `--validate-url` | string | Access token validation endpoint | |
 | `--version` | n/a | print version string | |
-| `--whitelist-domain` | string \| list | allowed domains for redirection after authentication. Prefix domain with a `.` or a `*.` to allow subdomains (e.g. `.example.com`, `*.example.com`) \[[2](#footnote2)\] | |
+| `--whitelist-domain` | string \| list | allowed domains for redirection after authentication. Prefix domain with a `.` or a `*.` to allow subdomains (e.g. `.example.com`, `*.example.com`) [^2] | |
 | `--trusted-ip` | string \| list | list of IPs or CIDR ranges to allow to bypass authentication (may be given multiple times). When combined with `--reverse-proxy` and optionally `--real-client-ip-header` this will evaluate the trust of the IP stored in an HTTP header by a reverse proxy rather than the layer-3/4 remote address. WARNING: trusting IPs has inherent security flaws, especially when obtaining the IP address from an HTTP header (reverse-proxy mode). Use this option only if you understand the risks and how to manage them. | |
 | `--encode-state` | bool | encode the state parameter as UrlEncodedBase64 | false |
 
-> ###### 1. Only these providers support `--cookie-refresh`: GitLab, Google and OIDC {#footnote1}
-> ###### 2. When using the `whitelist-domain` option, any domain prefixed with a `.` or a `*.` will allow any subdomain of the specified domain as a valid redirect URL. By default, only empty ports are allowed. This translates to allowing the default port of the URLs protocol (80 for HTTP, 443 for HTTPS, etc.) since browsers omit them. To allow only a specific port, add it to the whitelisted domain: `example.com:8080`. To allow any port, use `*`: `example.com:*`. {#footnote2}
+[^1]: Only these providers support `--cookie-refresh`: GitLab, Google and OIDC
+[^2]: When using the `whitelist-domain` option, any domain prefixed with a `.` or a `*.` will allow any subdomain of the specified domain as a valid redirect URL. By default, only empty ports are allowed. This translates to allowing the default port of the URLs protocol (80 for HTTP, 443 for HTTPS, etc.) since browsers omit them. To allow only a specific port, add it to the whitelisted domain: `example.com:8080`. To allow any port, use `*`: `example.com:*`.
 
 See below for provider specific options
 

docs/docs/configuration/providers/facebook.md

@@ -3,5 +3,5 @@ id: facebook
 title: Facebook
 ---
 
-1.  Create a new FB App from <https://developers.facebook.com/>
+1.  Create a new FB App from https://developers.facebook.com/
 2.  Under FB Login, set your Valid OAuth redirect URIs to `https://internal.yourcompany.com/oauth2/callback`

docs/docs/configuration/providers/github.md

@@ -14,30 +14,42 @@ org and team or collaborators.
 
 To restrict by organization only, include the following flag:
 
-    -github-org="": restrict logins to members of this organisation
+```shell
+    --github-org=""  # restrict logins to members of this organisation
+```
 
 To restrict within an organization to specific teams, include the following flag in addition to `-github-org`:
 
-    -github-team="": restrict logins to members of any of these teams (slug), separated by a comma
+```shell
+    --github-team=""  # restrict logins to members of any of these teams (slug), separated by a comma
+```
 
 If you would rather restrict access to collaborators of a repository, those users must either have push access to a 
 public repository or any access to a private repository:
 
-    -github-repo="": restrict logins to collaborators of this repository formatted as orgname/repo
+```shell
+    --github-repo=""  # restrict logins to collaborators of this repository formatted as orgname/repo
+```
 
 If you'd like to allow access to users with **read only** access to a **public** repository you will need to provide a 
 [token](https://github.com/settings/tokens) for a user that has write access to the repository. The token must be 
 created with at least the `public_repo` scope:
 
-    -github-token="": the token to use when verifying repository collaborators
+```shell
+    --github-token=""  # the token to use when verifying repository collaborators
+```
 
 To allow a user to log in with their username even if they do not belong to the specified org and team or collaborators, 
 separated by a comma
 
-    -github-user="": allow logins by username, separated by a comma
+```
+    --github-user="": allow logins by username, separated by a comma
+```
 
 If you are using GitHub enterprise, make sure you set the following to the appropriate url:
 
-    -login-url="http(s)://<enterprise github host>/login/oauth/authorize"
-    -redeem-url="http(s)://<enterprise github host>/login/oauth/access_token"
-    -validate-url="http(s)://<enterprise github host>/api/v3"
+```
+    --login-url="http(s)://<enterprise github host>/login/oauth/authorize"
+    --redeem-url="http(s)://<enterprise github host>/login/oauth/access_token"
+    --validate-url="http(s)://<enterprise github host>/api/v3"
+```

docs/docs/configuration/providers/gitlab.md

@@ -26,11 +26,15 @@ The following config should be set to ensure that the oauth will work properly.
 
 Restricting by group membership is possible with the following option:
 
-    --gitlab-group="mygroup,myothergroup": restrict logins to members of any of these groups (slug), separated by a comma
+```shell
+    --gitlab-group="mygroup,myothergroup"  # restrict logins to members of any of these groups (slug), separated by a comma
+```
 
 If you are using self-hosted GitLab, make sure you set the following to the appropriate URL:
 
+```shell
     --oidc-issuer-url="<your gitlab url>"
+```
 
 If your self-hosted GitLab is on a subdirectory (e.g. domain.tld/gitlab), as opposed to its own subdomain 
 (e.g. gitlab.domain.tld), you may need to add a redirect from domain.tld/oauth pointing at e.g. domain.tld/gitlab/oauth.

docs/docs/configuration/providers/keycloak_oidc.md

@@ -57,11 +57,11 @@ through "dedicated" client mappers._
            * **Valid redirect URIs** `https://internal.yourcompany.com/oauth2/callback`
                * _Save the configuration._
        * Under the **Credentials** tab you will now be able to locate `<your client's secret>`.
-2. Configure a dedicated *audience mapper* for your client by navigating to **Clients** -> **<your client's id>** -> **Client scopes**.
-* Access the dedicated mappers pane by clicking **<your client's id>-dedicated**, located under *Assigned client scope*.  
+2. Configure a dedicated *audience mapper* for your client by navigating to **Clients** -> **\<your client's id\>** -> **Client scopes**.
+* Access the dedicated mappers pane by clicking **\<your client's id\>-dedicated**, located under *Assigned client scope*.  
   _(It should have a description of "Dedicated scope and mappers for this client")_
     * Click **Configure a new mapper** and select **Audience**
-        * **Name** 'aud-mapper-<your client's id>'
+        * **Name** 'aud-mapper-\<your client's id\>'
         * **Included Client Audience** select `<your client's id>` from the dropdown.
             * _OAuth2 proxy can be set up to pass both the access and ID JWT tokens to your upstream services.
               If you require additional audience entries, you can use the **Included Custom Audience** field in addition 
@@ -105,7 +105,7 @@ Keycloak "realm roles" can be authorized using the `--allowed-role=<realm role n
 evaluated using `--allowed-role=<your client's id>:<client role name>`.
 
 You may limit the _realm roles_ included in the JWT tokens for any given client by navigating to:  
-**Clients** -> `<your client's id>` -> **Client scopes** ->  _<your client's id>-dedicated_ -> **Scope**  
+**Clients** -> `<your client's id>` -> **Client scopes** ->  _\<your client's id\>-dedicated_ -> **Scope**  
 Disabling **Full scope allowed** activates the **Assign role** option, allowing you to select which roles, if assigned 
 to a user, will be included in the user's JWT tokens. This can be useful when a user has many associated roles, and you 
 want to reduce the size and impact of the JWT token.

docs/docs/configuration/providers/openid_connect.md

@@ -39,22 +39,22 @@ To configure the OIDC provider for Dex, perform the following steps:
 
 4. In a second terminal, run the oauth2-proxy with the following args:
 
-    ```
-    -provider oidc
-    -provider-display-name "My OIDC Provider"
-    -client-id oauth2-proxy
-    -client-secret proxy
-    -redirect-url http://127.0.0.1:4180/oauth2/callback
-    -oidc-issuer-url http://127.0.0.1:5556/dex
-    -cookie-secure=false
-    -cookie-secret=secret
-    -email-domain kilgore.trout
+    ```shell
+    --provider oidc
+    --provider-display-name "My OIDC Provider"
+    --client-id oauth2-proxy
+    --client-secret proxy
+    --redirect-url http://127.0.0.1:4180/oauth2/callback
+    --oidc-issuer-url http://127.0.0.1:5556/dex
+    --cookie-secure=false
+    --cookie-secret=secret
+    --email-domain kilgore.trout
     ```
 
    To serve the current working directory as a website under the `/static` endpoint, add:
 
-    ```
-    -upstream file://$PWD/#/static/
+    ```shell
+    --upstream file://$PWD/#/static/
     ```
 
 5. Test the setup by visiting http://127.0.0.1:4180 or http://127.0.0.1:4180/static .
@@ -113,7 +113,7 @@ Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/example.c
 #### Okta - localhost
 
 1. Signup for developer account: https://developer.okta.com/signup/
-2. Create New `Web` Application: https://${your-okta-domain}/dev/console/apps/new
+2. Create New `Web` Application: https://$\{your-okta-domain\}/dev/console/apps/new
 3. Example Application Settings for localhost:
     * **Name:** My Web App
     * **Base URIs:** http://localhost:4180/
@@ -122,12 +122,12 @@ Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/example.c
     * **Group assignments:** `Everyone`
     * **Grant type allowed:** `Authorization Code` and `Refresh Token`
 4. Make note of the `Client ID` and `Client secret`, they are needed in a future step
-5. Make note of the **default** Authorization Server Issuer URI from: https://${your-okta-domain}/admin/oauth2/as
+5. Make note of the **default** Authorization Server Issuer URI from: https://$\{your-okta-domain\}/admin/oauth2/as
 6. Example config file `/etc/localhost.cfg`
-    ```
+    ```shell
     provider = "oidc"
     redirect_url = "http://localhost:4180/oauth2/callback"
-    oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"
+    oidc_issuer_url = "https://$\{your-okta-domain\}/oauth2/default"
     upstreams = [
         "http://0.0.0.0:8080"
     ]

docs/docs/installation.md

@@ -1,7 +1,6 @@
 ---
 id: installation
 title: Installation
-slug: /
 ---
 
 1.  Choose how to deploy:

docs/src/pages/index.md renamed to docs/docs/welcome.md

@@ -1,5 +1,6 @@
 ---
-title: Welcome to OAuth2 Proxy
+id: welcome
+title: Welcome
 hide_table_of_contents: true
 ---