Skip to content

Commit f2e639e

Browse files
kenjenkinskenjenkins
authored
start using 'shell-session' code blocks (#997)
Configure 'shell-session' as an additional language for syntax highlighting in code blocks. This differs from 'bash' highlighting in that lines not beginning with a shell symbol (e.g. '$') won't be treated as part of a shell command. Some of our existing code blocks use 'bash' along with line highlights to present interactive shell sessions. Convert these to use 'shell-session', adding '$' to any input lines. Note that the prism-react-renderer themes do not currently have styles for the 'shell-session' token types, so we need to define our own styles for these.
1 parent 7e7e5b8 commit f2e639e

File tree

8 files changed

+77
-53
lines changed

8 files changed

+77
-53
lines changed

‎content/_install-mkcert.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@ If you haven't, install `mkcert` following these [GitHub instructions](https://g
66

77
Create a trusted **root CA** and confirm the presence and names of your local CA files:
88

9-
```bash
10-
mkcert -install
9+
```shell-session
10+
$ mkcert -install
1111
The local CA is already installed in the system trust store! 👍
1212
The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! 👍
1313
14-
ls "$(mkcert -CAROOT)"
14+
$ ls "$(mkcert -CAROOT)"
1515
rootCA-key.pem rootCA.pem
1616
```
1717

‎content/docs/capabilities/mtls-services.mdx

+13-13
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ This guide uses the `localhost.pomerium.io` domain as the root domain (all subdo
6161

6262
1. Create a certificate and key for your example upstream service, OpenSSL:
6363

64-
```bash {1}
65-
mkcert openssl.localhost
64+
```shell-session
65+
$ mkcert openssl.localhost
6666
6767
Created a new certificate valid for the following names 📜
6868
- "openssl.localhost"
@@ -74,8 +74,8 @@ This guide uses the `localhost.pomerium.io` domain as the root domain (all subdo
7474

7575
1. Create a client certificate and key for Pomerium to use:
7676

77-
```bash {1}
78-
mkcert -client 'pomerium@localhost'
77+
```shell-session
78+
$ mkcert -client 'pomerium@localhost'
7979
8080
Created a new certificate valid for the following names 📜
8181
- "pomerium@localhost"
@@ -87,9 +87,9 @@ This guide uses the `localhost.pomerium.io` domain as the root domain (all subdo
8787

8888
1. Change ownership of the client certificate files and move them to Pomerium's configuration directory:
8989

90-
```bash
91-
sudo chown pomerium:pomerium pomerium@localhost-client*pem /etc/pomerium
92-
sudo mv pomerium@localhost-client*pem /etc/pomerium/
90+
```shell-session
91+
$ sudo chown pomerium:pomerium pomerium@localhost-client*pem /etc/pomerium
92+
$ sudo mv pomerium@localhost-client*pem /etc/pomerium/
9393
```
9494

9595
## Configure OpenSSL server
@@ -98,14 +98,14 @@ OpenSSL is installed or easily available for most 'nix-based operating systems l
9898

9999
1. In a terminal environment and the same directory where you created the certificate files, start an OpenSSL server process. Note that it will run in the foreground until stopped, so you will need another terminal environment to run additional commands:
100100

101-
```bash
102-
openssl s_server -key ./openssl.localhost-key.pem -cert ./openssl.localhost.pem -accept 44330 -www
101+
```shell-session
102+
$ openssl s_server -key ./openssl.localhost-key.pem -cert ./openssl.localhost.pem -accept 44330 -www
103103
```
104104

105105
You can confirm that the server is responding using `curl`:
106106

107-
```bash {1}
108-
curl -k https://localhost:44330
107+
```shell-session
108+
$ curl -k https://localhost:44330
109109
<HTML><BODY BGCOLOR="#ffffff">
110110
<pre>
111111
@@ -152,8 +152,8 @@ OpenSSL is installed or easily available for most 'nix-based operating systems l
152152
153153
1. Stop the OpenSSL server process (**Ctrl+C**) and start a new one with the additional flag `-Verify 1`:
154154

155-
```bash
156-
openssl s_server -Verify 1 -key ./openssl.localhost-key.pem -cert ./openssl.localhost.pem -accept 44330 -www
155+
```shell-session
156+
$ openssl s_server -Verify 1 -key ./openssl.localhost-key.pem -cert ./openssl.localhost.pem -accept 44330 -www
157157
```
158158

159159
1. When you refresh <https://openssl.localhost.pomium.io> in your browser, the connection will fail. Back in the terminal, the OpenSSL server should output errors containing:

‎content/docs/capabilities/tcp.mdx

+4-4
Original file line numberDiff line numberDiff line change
@@ -67,17 +67,17 @@ While HTTP routes can be consumed with just a normal browser, `pomerium-cli` or
6767

6868
To connect, you normally need just the external hostname and port of your TCP route:
6969

70-
```bash {1}
71-
pomerium-cli tcp redis.corp.example.com:6379
70+
```shell-session
71+
$ pomerium-cli tcp redis.corp.example.com:6379
7272
5:57PM INF tcptunnel: listening on 127.0.0.1:52046
7373
```
7474

7575
By default, `pomerium-cli` will start a listener on loopback on a random port.
7676

7777
On first connection, you will be sent through a standard Pomerium HTTP authentication flow. After completing this, your TCP connection should be established!
7878

79-
```bash {1}
80-
% redis-cli -h localhost -p 52046
79+
```shell-session
80+
$ redis-cli -h localhost -p 52046
8181
localhost:52046> keys *
8282
(empty array)
8383
localhost:52046>

‎content/docs/deploy/core.mdx

+6-6
Original file line numberDiff line numberDiff line change
@@ -83,22 +83,22 @@ Pomerium utilizes a [minimal](https://github.com/GoogleContainerTools/distroless
8383

8484
- `:vX.Y.Z`: which will pull the a [specific tagged release](https://github.com/pomerium/pomerium/tags).
8585

86-
```bash {1}
87-
docker run pomerium/pomerium:v0.1.0 --version
86+
```shell-session
87+
$ docker run pomerium/pomerium:v0.1.0 --version
8888
v0.1.0+53bfa4e
8989
```
9090

9191
- `:latest`: which will pull the [most recent tagged release](https://github.com/pomerium/pomerium/releases).
9292

93-
```bash {1}
94-
docker pull pomerium/pomerium:latest && docker run pomerium/pomerium:latest --version
93+
```shell-session
94+
$ docker pull pomerium/pomerium:latest && docker run pomerium/pomerium:latest --version
9595
v0.2.0+87e214b
9696
```
9797

9898
- `:main` : which will pull an image in sync with git's [main](https://github.com/pomerium/pomerium/tree/main) branch.
9999

100-
```bash {1}
101-
docker pull pomerium/pomerium:main
100+
```shell-session
101+
$ docker pull pomerium/pomerium:main
102102
```
103103

104104
Rootless images for official releases are also published to provide additional security. In these images, Pomerium runs as the `nonroot` user. Depending on your deployment environment, you may need to grant the container additional [capabilities](https://linux-audit.com/linux-capabilities-hardening-linux-binaries-by-removing-setuid/) or change the listening port from `443`.

‎content/docs/guides/helm.mdx

+6-6
Original file line numberDiff line numberDiff line change
@@ -92,8 +92,8 @@ If you haven't already, install cert-manager and create a CA issuer. You can fol
9292

9393
1. Confirm deployment with `kubectl get pods --namespace cert-manager`:
9494

95-
```bash {1}
96-
kubectl get pods --namespace cert-manager
95+
```shell-session
96+
$ kubectl get pods --namespace cert-manager
9797
NAME READY STATUS RESTARTS AGE
9898
cert-manager-5d7f97b46d-8g942 1/1 Running 0 33s
9999
cert-manager-cainjector-69d885bf55-6x5v2 1/1 Running 0 33s
@@ -122,8 +122,8 @@ If you haven't already, install cert-manager and create a CA issuer. You can fol
122122
123123
1. Apply and confirm:
124124
125-
```bash {1}
126-
kubectl apply -f issuer.yaml
125+
```shell-session
126+
$ kubectl apply -f issuer.yaml
127127
issuer.cert-manager.io/pomerium-issuer created
128128

129129
kubectl get issuers.cert-manager.io --namespace pomerium
@@ -155,8 +155,8 @@ If you haven't already, install cert-manager and create a CA issuer. You can fol
155155
kubectl apply -f pomerium-certificates.yaml
156156
```
157157

158-
```bash {1}
159-
kubectl get certificate
158+
```shell-session
159+
$ kubectl get certificate
160160
NAME READY SECRET AGE
161161
pomerium-cert True pomerium-tls 10s
162162
```

‎content/docs/guides/istio.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -114,8 +114,8 @@ Follow [Install Pomerium using Helm] to set up the Pomerium Ingress Controller a
114114
115115
1. When [defining a test service](/docs/deploy/k8s/quickstart#test-service), you should now see two containers for the service pod:
116116
117-
```bash {1}
118-
kubectl get pods
117+
```shell-session
118+
$ kubectl get pods
119119
NAME READY STATUS RESTARTS AGE
120120
...
121121
nginx-6955473668-cxprp 2/2 Running 0 19s

‎content/docs/guides/securing-tcp.mdx

+22-14
Original file line numberDiff line numberDiff line change
@@ -105,13 +105,17 @@ pomerium-cli tcp [hostname]:[port]
105105

106106
## Redis
107107

108-
````bash {2,6}
109-
# Start a proxy to redis in the background
110-
pomerium-cli tcp redis.localhost.pomerium.io:6379 --listen localhost:6379 &
108+
Start a proxy to redis in the background:
109+
110+
```shell-session
111+
$ pomerium-cli tcp redis.localhost.pomerium.io:6379 --listen localhost:6379 &
111112
3:01PM INF tcptunnel: listening on 127.0.0.1:6379
113+
```
112114

113-
# Start the redis client
114-
redis-cli
115+
Start the redis client:
116+
117+
```shell-session
118+
$ redis-cli
115119
3:01PM INF tcptunnel: opening connection dst=redis.localhost.pomerium.io:6379 proxy=redis.localhost.pomerium.io:443 secure=true
116120
3:01PM INF tcptunnel: opening connection dst=redis.localhost.pomerium.io:6379 proxy=redis.localhost.pomerium.io:443 secure=true
117121
3:01PM INF tcptunnel: connection established
@@ -125,20 +129,24 @@ redis-cli
125129
7) "type.googleapis.com/session.Session_version_set"
126130
8) "server_version_version_set"
127131
9) "server_version"
128-
10) "type.googleapis.com/directory.User_last_version"```
129-
````
132+
10) "type.googleapis.com/directory.User_last_version"
133+
```
130134

131135
## Postgres
132136

133137
In our example docker-compose, we have configured `supersecret` as the password for the `postgres` user.
134138

135-
```bash {2,6}
136-
# Start a proxy to postgres in the background
137-
pomerium-cli tcp pgsql.localhost.pomerium.io:5432 --listen localhost:5432 &
139+
Start a proxy to postgres in the background:
140+
141+
```shell-session
142+
$ pomerium-cli tcp pgsql.localhost.pomerium.io:5432 --listen localhost:5432 &
138143
3:07PM INF tcptunnel: listening on 127.0.0.1:5432
144+
```
145+
146+
Connect and list the schemas after password authentication:
139147

140-
# Connect and list the schemas after password authentication
141-
psql -h localhost -W -U postgres -c '\dn'
148+
```shell-session
149+
$ psql -h localhost -W -U postgres -c '\dn'
142150
Password:
143151
3:06PM INF tcptunnel: opening connection dst=pgsql.localhost.pomerium.io:5432 proxy=pgsql.localhost.pomerium.io:443 secure=true
144152
3:06PM INF tcptunnel: connection established
@@ -176,8 +184,8 @@ That's it! A Pomerium proxy will be started _automatically_ whenever you ssh to
176184

177185
In our example docker-compose, we have an SSH server configured with `supersecret` as the password for `myuser`.
178186

179-
```bash {1}
180-
ssh [email protected]
187+
```shell-session
188+
$ ssh [email protected]
181189
3:19PM INF tcptunnel: opening connection dst=ssh.localhost.pomerium.io:22 proxy=ssh.localhost.pomerium.io:443 secure=true
182190
3:19PM INF tcptunnel: connection established
183191
[email protected]'s password:

‎docusaurus.config.js

+21-5
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
// @ts-check
22
// Note: type annotations allow type checking and IDEs autocompletion
33

4-
const lightCodeTheme = require('prism-react-renderer/themes/github');
5-
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
4+
const githubCodeTheme = require('prism-react-renderer/themes/github');
5+
const draculaCodeTheme = require('prism-react-renderer/themes/dracula');
66
const dotenv = require('dotenv');
77

88
dotenv.config();
@@ -165,9 +165,9 @@ const config = {
165165
copyright: `Copyright © ${new Date().getFullYear()} Pomerium.`,
166166
},
167167
prism: {
168-
theme: lightCodeTheme,
169-
darkTheme: darkCodeTheme,
170-
additionalLanguages: ['actionscript', 'log', 'ini', 'nginx', 'rego'],
168+
theme: lightCodeTheme(),
169+
darkTheme: darkCodeTheme(),
170+
additionalLanguages: ['actionscript', 'log', 'ini', 'nginx', 'rego', 'shell-session'],
171171
},
172172
},
173173
stylesheets: [
@@ -184,6 +184,22 @@ const config = {
184184
],
185185
};
186186

187+
// The prism-react-renderer themes do not define styles for the 'shell-session'
188+
// token types, so define our own styles for these types here.
189+
function lightCodeTheme() {
190+
return {...githubCodeTheme, styles: githubCodeTheme.styles.concat([
191+
{types: ['shell-symbol'], style: { color: '#5d36c6' }},
192+
{types: ['command'], style: { color: '#1c1e21' }},
193+
{types: ['output'], style: { color: '#133369' }}
194+
])};
195+
}
196+
function darkCodeTheme() {
197+
return {...draculaCodeTheme, styles: draculaCodeTheme.styles.concat([
198+
{types: ['shell-symbol'], style: { color: '#c0a9ff' }},
199+
{types: ['output'], style: { color: '#e4e4c4' }}
200+
])};
201+
}
202+
187203
if (!process.env.ALGOLIA_APPID) {
188204
delete config.themeConfig.algolia;
189205
}

0 commit comments

Comments
 (0)