Command shortcode and refactoring (#55)

* add command shortcode and refactor first documents to use it * change more commands to new shortcode * format more commands to the shortcode * fix the last of the commands * add python code type * reafactor code fences to use proper language or command shortcode * fix typo in cloudformation * add command shortcode to best practices * add more comments to the shortcode Co-authored-by: Alexander Rashed <[email protected]>
localstack · Oct 7, 2021 · 7a81870 · 7a81870
1 parent 15e1b6b
commit 7a81870
Show file tree

Hide file tree

Showing 40 changed files with 328 additions and 422 deletions.
diff --git a/README.md b/README.md
@@ -42,6 +42,7 @@ alternatively:
 ## Best Practices
 
 Please follow these best practices when writing documentation here:
+- Use the custom `command` shortcode for all one-liner commands (also when their output is presented). Do not use it for bash scripts with comments. You can find a more detailed description here: https://github.com/localstack/docs/pull/55
 - Use the [`ref` or `relref` shortcode](https://gohugo.io/content-management/cross-references/#use-ref-and-relref) when creating non-external links (but still use the markdown native image linking, ref doesn't work there).
   You can either use `ref` or `relref`, the point is to have compile time internal-link checks (which works for both).
 - Stick to markdown if possible.
@@ -50,6 +51,8 @@ Please follow these best practices when writing documentation here:
 - For snippets, define the correct syntax highlighting.
   Here's a list of the supported languages:
   https://gohugo.io/content-management/syntax-highlighting/
+- If you want to hightlight a specific line, there's a feature for that: https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences
+  - This is also supported by the `command` shortcode!
 - Handling images can be a bit tedious with Hugo.
   If you want to use images in your post, create a new [leaf bundle directory](https://github.com/gohugoio/hugo/issues/1240) and put the image and the post (named `index.md`) in there (you can find examples in the docs already, f.e. the cognito service docs).
 
@@ -59,4 +62,4 @@ Please follow these best practices when writing documentation here:
   If you want to resize the image, use the `figure` shortcode.
 - Use relative paths to cross-reference between pages
 
-PS.: Feel free to add more best practices here (also give us a heads-up in [#sig-docs](https://localstack-cloud.slack.com/archives/C02FZH6UB2A)).
+PS.: Feel free to add more best practices here (also give us a heads-up in [#sig-docs](https://localstack-cloud.slack.com/archives/C02FZH6UB2A)).
diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss
@@ -18,5 +18,12 @@ $primary: #30638E !default;
     margin-top: 1em;
   }
 
+.command-prefix {
+    -moz-user-select: none;
+    -webkit-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
+}
+
 // workaround for https://github.com/google/docsy/issues/694
 @import "/css/shortcodes.css";
diff --git a/content/en/docs/Getting started/_index.md b/content/en/docs/Getting started/_index.md
@@ -48,25 +48,26 @@ Please make sure to install the following tools on your machine before moving on
 #### Installation
 The easiest way to install the LocalStack CLI is via `pip`:
 
-```sh
-python3 -m pip install localstack
-```
+{{< command >}}
+$ python3 -m pip install localstack
+{{< / command >}}
 
 {{< alert >}}
 **Note**: Please do **not** use `sudo` or the `root` user - LocalStack should be installed and started entirely under a local non-root user. 
 If you have problems with permissions in MacOS X Sierra, install with `python3 -m pip install --user localstack`.
 {{< /alert >}}
 
 Afterwards you should be able to use the LocalStack CLI in your terminal:
-```
+
+{{< command >}}
 $ localstack --help
 Usage: localstack [OPTIONS] COMMAND [ARGS]...
 
   The LocalStack Command Line Interface (CLI)
 
 Options:
 ...
-```
+{{< / command >}}
 
 #### Troubleshooting
 ##### The installation is successful, but I cannot execute `localstack` on my terminal.
@@ -75,16 +76,16 @@ If you can successfully install LocalStack using `pip` but you cannot use it in
 - If you are using a MacOS or Linux operating system, please make sure that the `PATH` is correctly set up - either system wide, or in your terminal.
 
 As a workaround you can call the LocalStack CLI python module directly:
-```sh
-python3 -m localstack.cli.main
-```
+{{< command >}}
+$ python3 -m localstack.cli.main
+{{< / command >}}
 
 #### Starting LocalStack with the LocalStack CLI
 By default, LocalStack is started inside a Docker container by running:
 
-```sh
-localstack start
-```
+{{< command >}}
+$ localstack start
+{{< / command >}}
 
 {{< alert title="Notes" >}}
 - This command starts all services provided by LocalStack.
@@ -108,9 +109,9 @@ You can check if `docker` is correctly configured on your machine by executing `
 
 #### Starting LocalStack with Docker
 You can start the Docker container simply by executing the following `docker run` command:
-```
-docker run --rm -it -p 4566:4566 -p 4571:4571 localstack/localstack
-```
+{{< command >}}
+$ docker run --rm -it -p 4566:4566 -p 4571:4571 localstack/localstack
+{{< / command >}}
 
 {{< alert title="Notes" >}}
 - This command pulls the current nighty build from the `master` branch (if you don't have the image locally) and **not** the latest supported version.
@@ -139,9 +140,9 @@ If you want to manually manage your Docker container, it's usually a good idea t
 #### Starting LocalStack with Docker-Compose
 You can use the [`docker-compose.yml` file from the official LocalStack repository](https://github.com/localstack/localstack/blob/master/docker-compose.yml) and use this command (currently requires `docker-compose` version 1.9.0+):
 
-```
-docker-compose up
-```
+{{< command >}}
+$ docker-compose up
+{{< / command >}}
 
 {{< alert title="Notes" >}}
 - This command pulls the current nighty build from the `master` branch (if you don't have the image locally) and **not** the latest supported version.
@@ -163,10 +164,10 @@ If you want to deply LocalStack in your [Kubernetes](https://kubernetes.io) clus
 
 #### Deploy LocalStack using Helm
 You can deploy LocalStack in a Kubernetes cluster by running these commands:
-```sh
-helm repo add localstack-repo https://helm.localstack.cloud
-helm upgrade --install localstack localstack-repo/localstack
-```
+{{< command >}}
+$ helm repo add localstack-repo https://helm.localstack.cloud
+$ helm upgrade --install localstack localstack-repo/localstack
+{{< / command >}}
 
 The Helm charts are not maintained in the main repository, but in a [separate one](https://github.com/localstack/helm-charts).
 

diff --git a/content/en/docs/Getting started/getting-started-pro/index.md b/content/en/docs/Getting started/getting-started-pro/index.md
@@ -31,31 +31,31 @@ You can find your API key in the [LocalStack Web Interface](https://app.localsta
 LocalStack Pro expects your API key to be present in the environment variable `LOCALSTACK_API_KEY`.
 Before starting LocalStack, please define the environment variable in your terminal like this:
 
-```sh
+{{< command >}}
 $ export LOCALSTACK_API_KEY=<your-api-key>
-```
+{{< / command >}}
 
 ### Starting LocalStack Pro using the CLI
 
 When starting LocalStack using the LocalStack CLI, you dot not have to perform any further steps (after exporting the environment variable).
-```sh
+{{< command >}}
 $ localstack start
-```
+{{< / command >}}
 
 LocalStack will detect the API key and properly pass it to the LocalStack container.
 
 ### Starting LocalStack Pro using Docker
 
 When starting LocalStack using a `docker run` command, you have to specify the API key using the `-e` flag for environment variables like this:
 
-{{< highlight bash "hl_lines=5" >}}
-docker run \
+{{< command "hl_lines=5" >}}
+$ docker run \
   --rm -it \
   -p 4566:4566 \
   -p 4571:4571 \
   -e LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY:- } \
   localstack/localstack
-{{< / highlight >}}
+{{< / command >}}
 
 For more information about starting LocalStack, take a look at our general [Getting Started]({{< ref "Getting started" >}}) guide.
 
@@ -79,9 +79,9 @@ If you want to make sure that LocalStack is only started if LocalStack Pro can b
 
 The easiest way to check if LocalStack Pro is activated is to check the health endpoing of LocalStack for a list of the running services:
 
-```
-curl localhost:4566/health | jq
-```
+{{< command >}}
+$ curl localhost:4566/health | jq
+{{< / command >}}
 
 If a Pro-only [service]({{< ref "Local AWS Services" >}}) -- like [XRay]({{< ref "XRay-Tracing" >}}) -- is running, LocalStack Pro has started successfully.
 
@@ -129,9 +129,9 @@ socket.gaierror: [Errno -3] Temporary failure in name resolution
 
 Please confirm this by using a tool like `dig`:
 
-```sh
-dig api.localstack.cloud
-```
+{{< command >}}
+$ dig api.localstack.cloud
+{{< / command >}}
 
 If the result has some other status than `status: NOERROR`, your machine cannot resolve this domain.
 

diff --git a/content/en/docs/Integrations/architect/index.md b/content/en/docs/Integrations/architect/index.md
@@ -17,23 +17,24 @@ If you are adapting an existing configuration, you might be able to skip certain
 ## Example
 
 ### Setup
-To use Architect in conjunction with Localstack, simply install the ```arclocal``` command (sources can be found [here](https://github.com/localstack/architect-local)).
-```
-npm install -g architect-local @architect/architect aws-sdk
-```
-The ``` arclocal``` command has the same usage as the ```arc``` command, so you can start right away.
+To use Architect in conjunction with Localstack, simply install the `arclocal` command (sources can be found [here](https://github.com/localstack/architect-local)).
+{{< command >}}
+$ npm install -g architect-local @architect/architect aws-sdk
+{{< /command >}}
+
+The `arclocal` command has the same usage as the `arc` command, so you can start right away.
 
 Create a test directory
 
-```bash
-mkdir architect_quickstart && cd architect_quickstart
-```
+{{< command >}}
+$ mkdir architect_quickstart && cd architect_quickstart
+{{< / command >}}
 
 then create an architect project
 
-```
-arclocal init
-```
+{{< command >}}
+$ arclocal init
+{{< / command >}}
 
 ### Deployment
 
@@ -43,9 +44,9 @@ Now you need to start LocalStack. The services you need to start are
  - cloudformation
 
 After LocalStack has started you can deploy your Architect setup via
-```
-arclocal deploy
-```
+{{< command >}}
+$ arclocal deploy
+{{< / command >}}
 
 ## Further reading
 

diff --git a/content/en/docs/Integrations/aws-cli/index.md b/content/en/docs/Integrations/aws-cli/index.md
@@ -13,38 +13,37 @@ All CLI commands that access [services that are implemented in LocalStack]({{< r
 There are two ways to use the CLI:
 
 * Use our `awslocal` drop-in replacement:
-  ```
-  awslocal kinesis list-streams
-  ```
+  {{< command >}}
+  $ awslocal kinesis list-streams
+  {{< / command >}}
 * Configure AWS test environment variables and add the `--endpoint-url=<localstack-url>` flag to your `aws` CLI invocations.
   For example:
-  ```
-  export AWS_ACCESS_KEY_ID="test"
-  export AWS_SECRET_ACCESS_KEY="test"
-  export AWS_DEFAULT_REGION="us-east-1"
+  {{< command >}}
+  $ export AWS_ACCESS_KEY_ID="test"
+  $ export AWS_SECRET_ACCESS_KEY="test"
+  $ export AWS_DEFAULT_REGION="us-east-1"
 
-  aws --endpoint-url=http://localhost:4566 kinesis list-streams
-  ```
+  $ aws --endpoint-url=http://localhost:4566 kinesis list-streams
+  {{< / command >}}
 
 ## AWS CLI
 
 Use the below command to install `aws`, if not installed already.
 
-```
-pip install awscli
-```
+{{< command >}}
+$ pip install awscli
+{{< / command >}}
 
 ### Setting up local region and credentials to run LocalStack
 
 aws requires the region and the credentials to be set in order to run the aws commands.
 Create the default configuration and the credentials.
 Below key will ask for the Access key id, secret Access Key, region & output format.
+Config & credential file will be created under ~/.aws folder
 
-```
-aws configure --profile default
-
-# Config & credential file will be created under ~/.aws folder
-```
+{{< command >}}
+$ aws configure --profile default
+{{< / command >}}
 
 {{< alert >}}
 **Note** Please use `test` as value for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to make pre-signed URLs for S3 buckets work.
@@ -68,14 +67,14 @@ The source code can be found on GitHub: https://github.com/localstack/awscli-loc
 
 You can install the `awslocal` command via `pip`:
 
-```
-pip install awscli-local[ver1]
-```
+{{< command >}}
+$ pip install awscli-local[ver1]
+{{< / command >}}
 
 Note that the command above also installs the latest version of the underlying AWS CLI version 1 (`awscli`) package. Use this command if you prefer to manage your own version of `awscli` (e.g., `v1`/`v2`) and install the wrapper script only:
-```
-pip install awscli-local
-```
+{{< command >}}
+$ pip install awscli-local
+{{< / command >}}
 
 {{< alert >}}
 **Note:** Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section]({{< ref "#limitations" >}}) for more details).
@@ -107,11 +106,11 @@ To work around this issue, you have 2 options:
   We do not recommend this, but it is technically possible.
   Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system:
 
-```bash
-virtualenv .venv
-. .venv/bin/activate
-pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip
-```
+{{< command >}}
+$ virtualenv .venv
+$ . .venv/bin/activate
+$ pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip
+{{< / command >}}
 
 ## AWS CLI v2
 
@@ -123,10 +122,11 @@ By default, the container running [amazon/aws-cli](https://docs.aws.amazon.com/c
 
 To ensure that the two docker containers can communicate create a network on the docker engine:
 
-```bash
+{{< command >}}
 $ docker network create localstack
 0c9cb3d37b0ea1bfeb6b77ade0ce5525e33c7929d69f49c3e5ed0af457bdf123
-```
+{{< / command >}}
+
 Then modify the `docker-compose.yml` specifying the network to use:
 
 ```yaml
@@ -138,24 +138,24 @@ networks:
 
 Run AWS Cli v2 docker container using this network (example):
 
-```bash
+{{< command >}}
 $ docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566 lambda list-functions
 {
     "Functions": []
 }
-```
+{{< / command >}}
 
 If you use AWS CLI v2 from a docker container often, create an alias:
 
-```bash
+{{< command >}}
 $ alias laws='docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566'
-```
+{{< / command >}}
 
 So you can type:
 
-```bash
+{{< command >}}
 $ laws lambda list-functions
 {
     "Functions": []
 }
-```
+{{< / command >}}