Skip to content
This repository was archived by the owner on Aug 7, 2025. It is now read-only.

docs: update README to point to new docs repo #1804

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 14 additions & 126 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,134 +1,22 @@
# LocalStack Docs
## LocalStack Documentation has moved!

Repository for [docs.localstack.cloud](https://docs.localstack.cloud).
[We've launched **LocalStack Docs v2**](https://blog.localstack.cloud/announcing-localstack-docs-v2/), introducing a complete systems-level redesign of our documentation experience. 😻 🎉

## Getting Started
## What’s New in LocalStack Docs v2?
- A brand-new Information Architecture
- Multiple cloud platforms (AWS, Snowflake, and more coming!)
- Task-based navigation focused on developer goals
- A clear separation of capabilities, integrations, tooling, and services
- A cleaner, more responsive user interface powered by Astro Starlight

### Basics
## Where Can I Find the New LocalStack Docs Repo?
Our new docs repo is right over here: [github.com/localstack/localstack-docs](https://github.com/localstack/localstack-docs).

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).
Our docs website is still here: [docs.localstack.cloud](https://docs.localstack.cloud/).

### Clone the repo
🗺️ ❤️ Our docs are still **100% open-source** 🗺️ ❤️, and we *love* [docs contributions from our community](https://github.com/localstack/localstack-docs/issues/new).

Clone this repository and initialize the Git submodules recursively (`themes/docsy` is a submodule that again has submodules for vendored assets like fontawesome).
Whether it’s fixing a typo or adding a new doc, we’d love your help in making LocalStack Docs even better!

git clone --recurse-submodules --depth 1 [email protected]:localstack/docs.git
💡 *Need ideas? Start a discussion in the [#docs channel of our community Slack](https://localstack-community.slack.com/archives/C097FSY72BX)!*

This performs a shallow clone, which leads to only the main branch being configured for your remote.
To be able to pull/push from/to all branches, please run:

git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" && git fetch

or:

git clone [email protected]:localstack/docs.git
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

or run in developer mode with automatic reload:

hugo serve --watch=true --disableFastRender -D

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.

Make sure to follow the best practices below when contributing content.

#### Updating developer hub applications

While contributing to the developer hub applications page i.e. editing `data/developerhub/applications.json` file, make sure to run the `create-applications.js` script in the `scripts` folder to create new application pages.

Example usage in the project root:

node scripts/create-applications.js

### Running pre-commit checks

You can run pre-commit checks to ensure that your changes are compliant with the repository's standards.

```bash
pip install pre-commit
pre-commit install
```

pre-commit will run automatically before each commit.
If you want to run it manually, use `pre-commit run`.

## Best Practices

Please follow these best practices when writing documentation in this repository:
- **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).

```text
# Do this
Configuration options are [here]({{< ref "/references/configuration" >}})

# Don't do this
Configuration options are [here](https://docs.localstack.cloud/references/configuration/)
```
- **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:

```markdown
{{< callout "warning" >}}
This will make your computer halt and catch fire!
{{< /callout >}}
```

## Troubleshooting

This section covers common issues when working with LocalStack Docs:

### Missing shortcodes

Example error:

```bash
Start building sites …
hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio
Error: Error building site: "/home/localstack/Repos/docs-test/content/en/get-started/_index.md:57:1": failed to extract shortcode: template for shortcode "alert" not found
Built in 45 ms
```

1. Make sure to correctly clone and initialize the git submodules of this repo.
For details see the section "[Clone the repo](#clone-the-repo)" above.
2. Delete the Hugo Module cache using `hugo mod clean` or `make clean`.