Add callout shortcode (#1260)

README.md

@@ -1,20 +1,20 @@
-LocalStack Docs
-=====================
+# LocalStack Docs
 
 Repository for [docs.localstack.cloud](https://docs.localstack.cloud).
 
 
-Getting Started
------------
+## Getting Started
 
 ### Basics
+
 LocalStack Docs is using the following technology stack:
 - [Hugo](https://gohugo.io) to generate the static site.
 - [Docsy](https://docsy.dev) as a theme for Hugo.
 - [GitHub Pages](https://pages.github.com/) to automatically deploy every commit on the `main` branch of this repository on [docs.localstack.cloud](https://docs.localstack.cloud).
 
 
 ### Clone the repo
+
 Clone this repository and initialize the Git submodules recursively (`themes/docsy` is a submodule that again has submodules for vendored assets like fontawesome).
 
     git clone --recurse-submodules --depth 1 git@github.com:localstack/docs.git
@@ -30,13 +30,17 @@ or:
     cd docs
     git submodule update --init --recursive
 
+
 ### Install Hugo
+
 LocalStack Docs is based on the [Hugo static site generator](https://gohugo.io).
 
 In order to contribute to LocalStack Docs, you need to [install Hugo](https://gohugo.io/getting-started/installing) in order to verify your changes. Make sure to install the _extended_ version of Hugo.
 You also need to make sure that `go` is installed in order to run hugo scripts. 
 
+
 ### Run locally
+
 Once you have Hugo installed, you can start your local server with the following command:
 
     hugo serve
@@ -47,7 +51,9 @@ or run in developer mode with automatic reload:
 
 Once the server is started, the locally served Docs are available at http://localhost:1313.
 
+
 ### Writing content
+
 The whole site is generated with Hugo, a powerful static-site generator.
 
 You can find an extensive documentation on how to use Hugo [in their docs](https://gohugo.io/documentation/), however most of the content is written in plain Markdown.
@@ -61,35 +67,42 @@ Example usage in the project root:
 
     node scripts/create-applications.js
 
+
 ## Best Practices
 
 Please follow these best practices when writing documentation in this repository:
-- 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).
+- **Stick to markdown** wherever possible.
+- **One sentence per line:** Use one line for each sentence in markdown.
+  Unless you add a backslash at the end of the line or add two new-lines, there won't be linebreak in the rendered text.
+- **Commands:** Use the `command` shortcode for all one-line 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.
+  If needed, you can also [highlight a specific line](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences).
+- **Internal links:** 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.
-- Use one line for each sentence in markdown.
-  If you don't add a backslash at the end of the line or add two new-lines, there won't be linebreak in the rendered text.
-- 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 highlight 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).
-
-  Then you can use the usual markdown syntax with a relative path (f.e.:
-  `![Alternative_Text](file_next_to_post.png)`).
+- **Code snippets:** For snippets, make sure you indicate the programming/markup language so that proper syntax highlighting is used.
+  Use `bash` only for Bash scripts, and use `text` for shell outputs or command examples.
+  The full list of the supported languages [here](https://gohugo.io/content-management/syntax-highlighting/).
+  If needed, you can also [highlight a specific line](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences) in the snippet.
+- **Images:** 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).
+  Then you can use the usual markdown syntax with a relative path (f.e.: `![Alternative_Text](file_next_to_post.png)`).
+  If you want to resize the image, use the `figure` or `img` shortcode, for example: `{{< img src="cockpit-init-check.png" class="img-fluid shadow rounded" width="150px" >}}`
+- **Callouts:** Use these to make content stand out.
+  The `callout` shortcode supports `note` (default), `tip` and `warning` levels.
+  Use it like so:
+  ```
+  {{< callout "warning" >}}
+  This will make your computer halt and catch fire!
+  {{< /callout >}}
+  ```
 
-  If you want to resize the image, use the `figure` or `img` shortcode. For example:
-  `{{< img src="cockpit-init-check.png" class="img-fluid shadow rounded" width="150px" >}}`
-
-PS.: Feel free to add more best practices here.
 
 ## Troubleshooting
+
 This section covers common issues when working with LocalStack Docs:
 
 ### Missing shortcodes
+
 Example error:
 ```
 Start building sites …

content/en/getting-started/auth-token/index.md

@@ -11,11 +11,11 @@ The Auth Token is a personal identifier used for user authentication outside the
 
 The Auth Token remains unchanged unless manually rotated by the user, regardless of any license assignment changes. You can locate your Auth Token on the [Getting Started page](https://app.localstack.cloud/getting-started) or the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) in the LocalStack Web Application.
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 -   Previously, API keys were required to activate the LocalStack core cloud emulator. These API keys are now being replaced by Auth Tokens.
 -   Currently, LocalStack supports both API Keys and Auth Tokens. However, API Keys will be discontinued in the upcoming major release of LocalStack.
 -   To update your LocalStack configuration, replace your API Key with an Auth Token. Use the `LOCALSTACK_AUTH_TOKEN` environment variable in place of `LOCALSTACK_API_KEY`.
-{{< /alert >}}
+{{< /callout >}}
 
 ## Managing your License
 
@@ -37,21 +37,21 @@ After initiating your trial or acquiring a license, proceed to assign it to a us
 
 If you have joined a workspace, you need to be assigned a license by the workspace administrator. In case of switching workspaces or licenses, you need to make sure that you are assigned to the correct license.
 
-{{< alert title="Note" >}}
+{{< callout "note" >}}
 If you do not assign a license, you will not be able to use LocalStack even if you have a valid Auth token.
-{{< /alert >}}
+{{< /callout >}}
 
 To view your own assigned license, visit the [My License page](https://app.localstack.cloud/workspace/my-license). You can further navigate to the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) to view your Auth Token.
 
 ## Configuring your Auth Token
 
 LocalStack requires the `LOCALSTACK_AUTH_TOKEN` environment variable to contain your Auth Token. You can configure your Auth Token in several ways, depending on your use case. The following sections describe the various methods of setting your Auth Token.
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning">}}
 -   It's crucial to keep your Auth Token confidential. Do not include it in source code management systems, such as Git repositories.
 -   Be aware that if an Auth Token is committed to a public repository, it's at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it.
 -   In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-token).
-{{< /alert >}}
+{{< /callout >}}
 
 ### Configuring your CI environment
 
@@ -79,9 +79,9 @@ You have the option to run your LocalStack container in the background by append
 
 The `localstack` CLI automatically detects the Auth Token and appropriately conveys it to the LocalStack container.
 
-{{< alert title="Note" >}}
+{{< callout "note" >}}
 If you are using LocalStack with an Auth Token, it's necessary to download the [LocalStack Pro image](https://docs.localstack.cloud/references/docker-images/#localstack-pro-image), which includes Pro services and several advanced features.
-{{< /alert >}}
+{{< /callout >}}
 
 ### Docker
 

content/en/getting-started/faq.md

@@ -196,11 +196,11 @@ docker pull public.ecr.aws/localstack/localstack-pro:latest
 
 ### How to increase IO performance for LocalStack's Docker image under Windows?
 
-{{< alert title="Note">}}
+{{< callout "note">}}
 Some options that are not part of the standard configuration may have unintended consequences for AWS services that operate within LocalStack.
 For example, these options may interfere with the functionality of AppSync function executor, RDS MySQL persistence and SageMaker.
 We advise you to exercise caution.
-{{< /alert >}}
+{{< /callout >}}
 
 You can change the LocalStack `volume` folder to use the WSL Linux file system instead of the Windows host folder.
 To do so, you need to change the [`docker-compose.yml`](https://github.com/localstack/localstack/blob/master/docker-compose-pro.yml) file and add the following lines:

content/en/getting-started/help-and-support.md

@@ -92,7 +92,7 @@ LocalStack Web Application is available to all licensed users. To create a suppo
 
 You can optionally choose to continue the conversation via email or via the Web Application.
 
-{{< alert title="Note" >}}
+{{< callout "note" >}}
 In many scenarios, we ask our customers to use Diagnosis endpoint to help us retrieve additional information. To use LocalStack's Diagnosis endpoint:
 
 - Set the environment variable `LS_LOG=trace`
@@ -102,4 +102,4 @@ In many scenarios, we ask our customers to use Diagnosis endpoint to help us ret
 - Send the output file to our Slack chat
 
 Ensure that you avoid sending the diagnostic output to public channels or forums, as it may contain sensitive information.
-{{< /alert >}}
+{{< /callout >}}

content/en/getting-started/installation.md

@@ -59,10 +59,10 @@ $ python3 -m pip install --upgrade localstack
 {{< / command >}}
 {{% /markdown %}}
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 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 >}}
+{{< /callout >}}
 </details>
 {{< /tab >}}
 
@@ -118,9 +118,9 @@ Afterwards you can install the LocalStack CLI in your Python environment with:
 $ python3 -m pip install --upgrade localstack
 {{< / command >}}
 {{% /markdown %}}
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 Do not use `sudo` or the `root` user - LocalStack should be installed and started entirely under a local non-root user.
-{{< /alert >}}
+{{< /callout >}}
 </details>
 {{< /tab >}}
 
@@ -145,9 +145,9 @@ $ python3 -m pip install --upgrade localstack
 {{< / command >}}
 {{% /markdown %}}
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 Do not use `sudo` or the `root` user - LocalStack should be installed and started entirely under a local non-root user.
-{{< /alert >}}
+{{< /callout >}}
 </details>
 {{< /tab >}}
 
@@ -166,19 +166,19 @@ $ python3 -m pip install --upgrade localstack
 {{< / command >}}
 {{% /markdown %}}
 
-{{< alert title="Note" >}}
+{{< callout "note" >}}
 To download a specific version of LocalStack, check out our [release page](https://github.com/localstack/localstack) and download it in the following manner:
 {{< command >}}
 $ python3 -m pip install localstack==<version>
 {{< / command >}}
 {{% markdown %}}
 Here `<version>` depicts the particular LocalStack version that you would like to download and use.
 {{% /markdown %}}
-{{< /alert >}}
+{{< /callout >}}
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 Do not use `sudo` or the `root` user - LocalStack should be installed and started entirely under a local non-root user.
-{{< /alert >}}
+{{< /callout >}}
 {{< /tab >}}
 {{< /tabpane >}}
 
@@ -285,7 +285,7 @@ Start the container by running the following command:
 $ docker-compose up
 {{< / command >}}
 
-{{< alert title="Notes" >}}
+{{< callout "note" >}}
 - This command pulls the current nightly build from the `master` branch (if you don't have the image locally) and **not** the latest supported version.
   If you want to use a specific version, set the appropriate localstack image tag at `services.localstack.image` in the `docker-compose.yml` file (for example `localstack/localstack:<version>`).
 
@@ -303,7 +303,7 @@ $ docker-compose up
   Please consider removing it, if this functionality is needed.
 
 - To configure an auth token, refer to the [auth token]({{< ref "auth-token" >}}) documentation.
-{{< /alert >}}
+{{< /callout >}}
 
 Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables).
 We recommend using the LocalStack CLI to validate your configuration, which will print warning messages in case it detects any potential misconfigurations:
@@ -345,7 +345,7 @@ docker run \
   localstack/localstack-pro{{< /tab >}}
 {{< /tabpane >}}
 
-{{< alert title="Notes" >}}
+{{< callout "note" >}}
 - This command pulls the current nightly build from the `master` branch (if you don't have the image locally) and **not** the latest supported version.
   If you want to use a specific version of LocalStack, use the appropriate tag: `docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:<tag>`. Check-out the [LocalStack releases](https://github.com/localstack/localstack/releases) to know more about specific LocalStack versions.
 
@@ -362,7 +362,7 @@ docker run \
 - To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`.
 
 - To configure an auth token, refer to the [auth token]({{< ref "auth-token" >}}) documentation.
-{{< /alert >}}
+{{< /callout >}}
 
 ### Helm
 

content/en/getting-started/quickstart/index.md

@@ -89,13 +89,13 @@ pip install -r requirements-dev.txt
 {{< /tab >}}
 {{< /tabpane >}}
 
-{{< alert title="Note" >}}
+{{< callout "tip" >}}
 If you are encountering issues with the installation of the packages, such as Pillow, ensure you use the same version as the Python Lambdas (3.9) for Pillow to work. If you're using <a href="https://github.com/pyenv/pyenv">pyenv</a>, install and activate Python 3.9 with the following commands:
 {{< command >}}
 $ pyenv install 3.9.0
 $ pyenv global 3.9.0
 {{< / command >}}
-{{< /alert >}}
+{{< /callout >}}
 
 ### Setup the serverless image resizer
 
@@ -109,9 +109,9 @@ $ bin/deploy.sh
 
 Alternatively, you can follow these instructions to deploy the sample application manually step-by-step.
 
-{{< alert title="Note" >}}
+{{< callout "tip" >}}
 In absence of the `awslocal` wrapper, you can use the `aws` CLI directly, by configuring an [endpoint URL](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#configuring-an-endpoint-url) or a [custom profile](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#configuring-a-custom-profile) like `localstack`. You can then swap `awslocal` with `aws --endpoint-url=http://localhost:4566` or `aws --profile=localstack` in the commands below.
-{{< /alert >}}
+{{< /callout >}}
 
 #### Create the S3 buckets
 
@@ -323,4 +323,4 @@ Congratulations on deploying an AWS application locally using LocalStack! To exp
 - [Tutorials]({{< ref "tutorials" >}}): Check out our tutorials to learn how to use LocalStack across various AWS services and application stacks.
 - [User Guide]({{< ref "user-guide" >}}): Explore LocalStack's emulated AWS services, third-party integrations, tooling, CI service providers, and more in our User Guide.
 - [References]({{< ref "references" >}}): Dive into LocalStack references for a comprehensive understanding of key internals and technical details.
-- [Blog](https://blog.localstack.cloud): Read our blog posts about LocalStack and the latest enhancements for a better local development and testing experience.
+- [Blog](https://blog.localstack.cloud): Read our blog posts about LocalStack and the latest enhancements for a better local development and testing experience.

content/en/references/api-key.md

@@ -9,22 +9,22 @@ aliases:
   - /getting-started/api-key/
 ---
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 -   LocalStack is transitioning from API Keys to Auth Tokens for activation. Auth Tokens streamline license management and remove the need for developers to adjust their setup when license changes occur.
 -   For detailed information and guidance on migrating your LocalStack setup to Auth Tokens, please consult our [Auth Token documentation]({{< ref "auth-token" >}}).
 -   API Keys will remain functional for LocalStack Pro and Enterprise users until the next major release. Following this release, LocalStack Pro and Enterprise will exclusively use Auth Tokens.
-{{< /alert >}}
+{{< /callout >}}
 
 The LocalStack API key is a unique identifier to activate your LocalStack license needed to start LocalStack Pro.
 You can find your API key in the [LocalStack Web app](https://app.localstack.cloud/account/apikeys).
 This guide demonstrates how you can use your new LocalStack licenses and go over some best practices regarding the usage, activation, and safety of your LocalStack API key.
 
-{{< alert title="Important" color="danger" >}}
+{{< callout "warning" >}}
 - Avoid sharing your API key with anyone. Ensure that you do not commit it to any source code management systems (like Git repositories).
 - If you push an API key to a public repository, it has potentially been exposed and might remain in the history (even if you try to rewrite it).
 - If you accidentally publish your API key, please [contact us](https://localstack.cloud/contact/) immediately to get your API key rotated!
 - If you want to use your API key in your CI environment, check out our [CI documentation]({{< ref "user-guide/ci" >}}) to see the proper way to handle secrets in your CI environment to store your API key securely.
-{{< /alert >}}
+{{< /callout >}}
 
 ### Starting LocalStack via CLI
 
@@ -44,9 +44,9 @@ You can optionally run your LocalStack container in background mode by adding th
 
 The `localstack` CLI will detect the API key and properly pass it to the LocalStack container.
 
-{{< alert title="Note" >}}
+{{< callout >}}
 If you are using LocalStack with an API Key, you need to pull the [LocalStack Pro image](https://docs.localstack.cloud/references/docker-images/#localstack-pro-image) that includes the Pro services and several other advanced features.
-{{< /alert >}}
+{{< /callout >}}
 
 ### Starting LocalStack via Docker