Docs: Convert Console Config to Table (#3109)

* update enterprise config doc

* add anchors to key names

docs/.vuepress/styles/palette.styl

@@ -50,6 +50,11 @@ $MQMobileNarrow = 419px
     &:hover, &.router-link-active
       color lighten($textColor, 8%) !important
 
+a.entRef-anchor
+  visibility: hidden
+  display: block
+  position: relative
+  top: -4.25rem
 
 .dropdown-wrapper
   .dropdown-title

docs/enterprise/pomerium-console_serve.yaml

@@ -3,63 +3,67 @@ usage: pomerium-console serve [flags]
 options:
 - name: administrators
   usage: |
-    a list of user ids, names or emails to make administrators, useful for bootstrapping
+    A list of user ids, names or emails to make administrators. Useful for bootstrapping.
 - name: audience
   default_value: '[]'
-  usage: A list of audiences for verifying signing key
+  usage: A list of audiences for verifying the signing key.
 - name: authenticate-service-url
-  usage: URL for the authenticate service
+  usage: |
+    URL for the Authenticate Service. Required for Device Registration.
 - name: bind-addr
   default_value: :8701
-  usage: the address to listen on
+  usage: The address the Pomerium Console will listen on.
 - name: customer-id
-  usage: the customer id
+  usage: The customer ID
 - name: database-encryption-key
   usage: |
-    base64-encoded encryption key for encrypting sensitive data in the database
+    The base64-encoded encryption key for encrypting sensitive data in the database.
 - name: database-url
   default_value: |
     postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable
-  usage: the database to connect to
+  usage: The database Pomerium Enterprise Console will use.
 - name: databroker-service-url
   default_value: http://localhost:5443
-  usage: the databroker service url
+  usage: The databroker service URL.
 - name: debug-config-dump
   default_value: "false"
-  usage: dump databroker configuration
+  usage: |
+    Dumps the Databroker configuration. This is a debug option to be used only when specified by Pomerium Support.
+- name: disable-remote-diagnostics
+  default_value: "true"
+  usage: Disable remote diagnostics.
 - name: disable-validation
   default_value: "false"
-  usage: disable config validation
+  usage: Disable config validation.
-- name: enable-remote-diagnostics
-  default_value: "false"
-  usage: enable remote diagnostics
 - name: grpc-addr
   default_value: :8702
-  usage: the address to listen for gRPC on
+  usage: The address to listen for gRPC on.
 - name: help
   shorthand: h
   default_value: "false"
   usage: help for serve
-- name: license
+- name: license-key
-  usage: license JWT
+  usage: 'Required: Provide the license key issued by your account team.'
 - name: override-certificate-name
   usage: |
-    override the certificate name used for the databroker connection
+    Overrides the certificate name used for the databroker connection.
 - name: prometheus-data-dir
-  usage: path to prometheus data
+  usage: The path to Prometheus data
 - name: prometheus-listen-addr
   default_value: 127.0.0.1:9090
-  usage: embedded prometheus listen address as host:port
+  usage: |
+    When set, embedded Prometheus listens at this address. Set as `host:port`
 - name: prometheus-scrape-interval
   default_value: 10s
-  usage: prometheus scrape frequency
+  usage: The Prometheus scrape frequency
 - name: prometheus-url
-  usage: url to access prometheus metrics server
+  usage: The URL to access the Prometheus metrics server.
 - name: shared-secret
-  usage: base64-encoded shared secret for signing JWTs
+  usage: |
+    The base64-encoded secret for signing JWTs, shared with OSS Pomerium.
 - name: signing-key
   usage: |
-    base64-encoded signing key (public or private) for verifying JWTs
+    base64-encoded signing key (public or private) for verifying JWTs. This option is deprecated in favor of `authenticate-service-url`.
 - name: tls-ca
   usage: base64-encoded string of tls-ca
 - name: tls-ca-file
@@ -71,14 +75,14 @@ options:
 - name: tls-insecure-skip-verify
   default_value: "false"
   usage: |
-    disable remote hosts TLS certificate chain and hostname check
+    Disable remote hosts TLS certificate chain and hostname checks.
 - name: tls-key
   usage: base64-encoded string of tls-key
 - name: tls-key-file
   usage: file storing tls-key
 - name: use-static-assets
   default_value: "true"
-  usage: when false, forward static requests to localhost:3000
+  usage: When false, forward static requests to `localhost:3000`.
 inherited_options:
 - name: config
   usage: Set configuration file path

docs/enterprise/reference/config.md

@@ -10,182 +10,34 @@ meta:
 
 The keys listed below can be applied in Pomerium Console's `config.yaml` file, or applied as environment variables (in uppercase, replacing `-` with `_`).
 
-## administrators
+| Name    | Description | Default Value |
-
+|:--------|:-------------|---------------|
-a list of user ids, names or emails to make administrators, useful for bootstrapping
+| <a class="entRef-anchor" id="administrators">#</a><a href=#administrators>administrators</a> | A list of user ids, names or emails to make administrators. Useful for bootstrapping. | none |
-
+| <a class="entRef-anchor" id="audience">#</a><a href=#audience>audience</a> | A list of audiences for verifying the signing key. | `[]` |
-
+| <a class="entRef-anchor" id="authenticate-service-url">#</a><a href=#authenticate-service-url>authenticate-service-url</a> | URL for the Authenticate Service. Required for Device Registration. | none |
-**Default value:** `none`
+| <a class="entRef-anchor" id="bind-addr">#</a><a href=#bind-addr>bind-addr</a> | The address the Pomerium Console will listen on. | `:8701` |
-
+| <a class="entRef-anchor" id="customer-id">#</a><a href=#customer-id>customer-id</a> | The customer ID | none |
-## audience
+| <a class="entRef-anchor" id="database-encryption-key">#</a><a href=#database-encryption-key>database-encryption-key</a> | The base64-encoded encryption key for encrypting sensitive data in the database. | none |
-
+| <a class="entRef-anchor" id="database-url">#</a><a href=#database-url>database-url</a> | The database Pomerium Enterprise Console will use. | `postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable` |
-A list of audiences for verifying signing key
+| <a class="entRef-anchor" id="databroker-service-url">#</a><a href=#databroker-service-url>databroker-service-url</a> | The databroker service URL. | `http://localhost:5443` |
-
+| <a class="entRef-anchor" id="debug-config-dump">#</a><a href=#debug-config-dump>debug-config-dump</a> | Dumps the Databroker configuration. This is a debug option to be used only when specified by Pomerium Support. | `false` |
-**Default value:** `[]`
+| <a class="entRef-anchor" id="disable-remote-diagnostics">#</a><a href=#disable-remote-diagnostics>disable-remote-diagnostics</a> | Disable remote diagnostics. | `true` |
-
+| <a class="entRef-anchor" id="disable-validation">#</a><a href=#disable-validation>disable-validation</a> | Disable config validation. | `false` |
-## authenticate-service-url
+| <a class="entRef-anchor" id="grpc-addr">#</a><a href=#grpc-addr>grpc-addr</a> | The address to listen for gRPC on. | `:8702` |
-
+| <a class="entRef-anchor" id="help">#</a><a href=#help>help</a> | help for serve | `false` |
-URL for the authenticate service
+| <a class="entRef-anchor" id="license-key">#</a><a href=#license-key>license-key</a> | Required: Provide the license key issued by your account team. | none |
-
+| <a class="entRef-anchor" id="override-certificate-name">#</a><a href=#override-certificate-name>override-certificate-name</a> | Overrides the certificate name used for the databroker connection. | none |
-**Default value:** `none`
+| <a class="entRef-anchor" id="prometheus-data-dir">#</a><a href=#prometheus-data-dir>prometheus-data-dir</a> | The path to Prometheus data | none |
-
+| <a class="entRef-anchor" id="prometheus-listen-addr">#</a><a href=#prometheus-listen-addr>prometheus-listen-addr</a> | When set, embedded Prometheus listens at this address. Set as `host:port` | `127.0.0.1:9090` |
-## bind-addr
+| <a class="entRef-anchor" id="prometheus-scrape-interval">#</a><a href=#prometheus-scrape-interval>prometheus-scrape-interval</a> | The Prometheus scrape frequency | `10s` |
-
+| <a class="entRef-anchor" id="prometheus-url">#</a><a href=#prometheus-url>prometheus-url</a> | The URL to access the Prometheus metrics server. | none |
-the address to listen on
+| <a class="entRef-anchor" id="shared-secret">#</a><a href=#shared-secret>shared-secret</a> | The base64-encoded secret for signing JWTs, shared with OSS Pomerium. | none |
-
+| <a class="entRef-anchor" id="signing-key">#</a><a href=#signing-key>signing-key</a> | base64-encoded signing key (public or private) for verifying JWTs. This option is deprecated in favor of `authenticate-service-url`. | none |
-**Default value:** `:8701`
+| <a class="entRef-anchor" id="tls-ca">#</a><a href=#tls-ca>tls-ca</a> | base64-encoded string of tls-ca | none |
-
+| <a class="entRef-anchor" id="tls-ca-file">#</a><a href=#tls-ca-file>tls-ca-file</a> | file storing tls-ca | none |
-## customer-id
+| <a class="entRef-anchor" id="tls-cert">#</a><a href=#tls-cert>tls-cert</a> | base64-encoded string of tls-cert | none |
-
+| <a class="entRef-anchor" id="tls-cert-file">#</a><a href=#tls-cert-file>tls-cert-file</a> | file storing tls-cert | none |
-the customer id
+| <a class="entRef-anchor" id="tls-insecure-skip-verify">#</a><a href=#tls-insecure-skip-verify>tls-insecure-skip-verify</a> | Disable remote hosts TLS certificate chain and hostname checks. | `false` |
-
+| <a class="entRef-anchor" id="tls-key">#</a><a href=#tls-key>tls-key</a> | base64-encoded string of tls-key | none |
-**Default value:** `none`
+| <a class="entRef-anchor" id="tls-key-file">#</a><a href=#tls-key-file>tls-key-file</a> | file storing tls-key | none |
-
+| <a class="entRef-anchor" id="use-static-assets">#</a><a href=#use-static-assets>use-static-assets</a> | When false, forward static requests to `localhost:3000`. | `true` |
-## database-encryption-key
-
-base64-encoded encryption key for encrypting sensitive data in the database
-
-
-**Default value:** `none`
-
-## database-url
-
-the database to connect to
-
-**Default value:** `postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable
-`
-
-## databroker-service-url
-
-the databroker service url
-
-**Default value:** `http://localhost:5443`
-
-## debug-config-dump
-
-dump databroker configuration
-
-**Default value:** `false`
-
-## disable-validation
-
-disable config validation
-
-**Default value:** `false`
-
-## enable-remote-diagnostics
-
-enable remote diagnostics
-
-**Default value:** `false`
-
-## grpc-addr
-
-the address to listen for gRPC on
-
-**Default value:** `:8702`
-
-## help
-
-help for serve
-
-**Default value:** `false`
-
-## license
-
-license JWT
-
-**Default value:** `none`
-
-## override-certificate-name
-
-override the certificate name used for the databroker connection
-
-
-**Default value:** `none`
-
-## prometheus-data-dir
-
-path to prometheus data
-
-**Default value:** `none`
-
-## prometheus-listen-addr
-
-embedded prometheus listen address as host:port
-
-**Default value:** `127.0.0.1:9090`
-
-## prometheus-scrape-interval
-
-prometheus scrape frequency
-
-**Default value:** `10s`
-
-## prometheus-url
-
-url to access prometheus metrics server
-
-**Default value:** `none`
-
-## shared-secret
-
-base64-encoded shared secret for signing JWTs
-
-**Default value:** `none`
-
-## signing-key
-
-base64-encoded signing key (public or private) for verifying JWTs
-
-
-**Default value:** `none`
-
-## tls-ca
-
-base64-encoded string of tls-ca
-
-**Default value:** `none`
-
-## tls-ca-file
-
-file storing tls-ca
-
-**Default value:** `none`
-
-## tls-cert
-
-base64-encoded string of tls-cert
-
-**Default value:** `none`
-
-## tls-cert-file
-
-file storing tls-cert
-
-**Default value:** `none`
-
-## tls-insecure-skip-verify
-
-disable remote hosts TLS certificate chain and hostname check
-
-
-**Default value:** `false`
-
-## tls-key
-
-base64-encoded string of tls-key
-
-**Default value:** `none`
-
-## tls-key-file
-
-file storing tls-key
-
-**Default value:** `none`
-
-## use-static-assets
-
-when false, forward static requests to localhost:3000
-
-**Default value:** `true`

scripts/generate-console-pages.js

@@ -69,15 +69,14 @@ meta:
 
 The keys listed below can be applied in Pomerium Console's \`config.yaml\` file, or applied as environment variables (in uppercase, replacing \`-\` with \`_\`).
 
+| Name    | Description | Default Value |
+|:--------|:-------------|---------------|
 `;
   const keySection = (obj) => {
     //console.log(JSON.stringify(obj.name)) // For Debugging
-    let header = `## ` + obj.name + "\n\n";
+    let name = `| <a class="entRef-anchor" id="${obj.name}">#</a><a href=#${obj.name}>` + obj.name + `</a> |`;
-    let body = `${obj.usage}
+    let body = ` ${(obj.usage).replace(/\n/g, '')} | ${obj.default_value ? `\`${obj.default_value.replace(/\n/g, '')}\`` : `none`} |`;
-
+    return name + body;
-**Default value:** \`${obj.default_value ? obj.default_value : `none`}\`
-`;
-    return header + body;
   };
 
   let content =