docs: update README to point to new docs repo by quetzalliwrites · Pull Request #1804 · localstack/docs

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 git@github.com: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 git@github.com: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月04日T09: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`.

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

Uh oh!

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

Filter by extension

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing