|
1 |
| -# LocalStack Docs |
| 1 | +## LocalStack Documentation has moved! |
2 | 2 |
|
3 |
| -Repository for [docs.localstack.cloud](https://docs.localstack.cloud). |
| 3 | +We've launched [**LocalStack Docs v2**](https://github.com/localstack/localstack-docs), introducing a complete systems-level redesign of our documentation experience. 😻 🎉 |
4 | 4 |
|
5 |
| -## Getting Started |
| 5 | +## What’s New in LocalStack Docs v2? |
| 6 | +- A brand-new Information Architecture |
| 7 | +- Multiple cloud platforms (AWS, Snowflake, and more coming!) |
| 8 | +- Task-based navigation focused on developer goals |
| 9 | +- A clear separation of capabilities, integrations, tooling, and services |
| 10 | +- A cleaner, more responsive user interface powered by Astro Starlight |
6 | 11 |
|
7 |
| -### Basics |
| 12 | +## Where Can I Find the New LocalStack Docs Repo? |
| 13 | +Our new docs repo is right over here: [github.com/localstack/localstack-docs](https://github.com/localstack/localstack-docs). |
8 | 14 |
|
9 |
| -LocalStack Docs is using the following technology stack: |
10 |
| -- [Hugo](https://gohugo.io) to generate the static site. |
11 |
| -- [Docsy](https://docsy.dev) as a theme for Hugo. |
12 |
| -- [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). |
| 15 | +🗺️ ❤️ Our docs are still **100% open-source** 🗺️ ❤️, and we *love* [docs contributions from our community](https://github.com/localstack/localstack-docs/issues/new). |
13 | 16 |
|
14 |
| -### Clone the repo |
| 17 | +Whether it’s fixing a typo or adding a new doc, we’d love your help in making LocalStack Docs even better! |
15 | 18 |
|
16 |
| -Clone this repository and initialize the Git submodules recursively (`themes/docsy` is a submodule that again has submodules for vendored assets like fontawesome). |
| 19 | +💡 *Need ideas? Start a discussion in the [#docs channel of our community Slack](https://localstack-community.slack.com/archives/C097FSY72BX)!* |
17 | 20 |
|
18 |
| - git clone --recurse-submodules --depth 1 [email protected]:localstack/docs.git |
19 |
| - |
20 |
| -This performs a shallow clone, which leads to only the main branch being configured for your remote. |
21 |
| -To be able to pull/push from/to all branches, please run: |
22 |
| - |
23 |
| - git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" && git fetch |
24 |
| - |
25 |
| -or: |
26 |
| - |
27 |
| - git clone [email protected]:localstack/docs.git |
28 |
| - cd docs |
29 |
| - git submodule update --init --recursive |
30 |
| - |
31 |
| -### Install Hugo |
32 |
| - |
33 |
| -LocalStack Docs is based on the [Hugo static site generator](https://gohugo.io). |
34 |
| - |
35 |
| -In order to contribute to LocalStack Docs, you need to [install Hugo](https://gohugo.io/getting-started/installing) in order to verify your changes. |
36 |
| -Make sure to install the _extended_ version of Hugo. |
37 |
| -You also need to make sure that `go` is installed in order to run hugo scripts. |
38 |
| - |
39 |
| -### Run locally |
40 |
| - |
41 |
| -Once you have Hugo installed, you can start your local server with the following command: |
42 |
| - |
43 |
| - hugo serve |
44 |
| - |
45 |
| -or run in developer mode with automatic reload: |
46 |
| - |
47 |
| - hugo serve --watch=true --disableFastRender -D |
48 |
| - |
49 |
| -Once the server is started, the locally served Docs are available at http://localhost:1313. |
50 |
| - |
51 |
| -### Writing content |
52 |
| - |
53 |
| -The whole site is generated with Hugo, a powerful static-site generator. |
54 |
| - |
55 |
| -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. |
56 |
| - |
57 |
| -Make sure to follow the best practices below when contributing content. |
58 |
| - |
59 |
| -#### Updating developer hub applications |
60 |
| - |
61 |
| -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. |
62 |
| - |
63 |
| -Example usage in the project root: |
64 |
| - |
65 |
| - node scripts/create-applications.js |
66 |
| - |
67 |
| -### Running pre-commit checks |
68 |
| - |
69 |
| -You can run pre-commit checks to ensure that your changes are compliant with the repository's standards. |
70 |
| - |
71 |
| -```bash |
72 |
| -pip install pre-commit |
73 |
| -pre-commit install |
74 |
| -``` |
75 |
| - |
76 |
| -pre-commit will run automatically before each commit. |
77 |
| -If you want to run it manually, use `pre-commit run`. |
78 |
| - |
79 |
| -## Best Practices |
80 |
| - |
81 |
| -Please follow these best practices when writing documentation in this repository: |
82 |
| -- **Stick to markdown** wherever possible. |
83 |
| -- **One sentence per line:** Use one line for each sentence in markdown. |
84 |
| - 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. |
85 |
| -- **Commands:** Use the `command` shortcode for all one-line commands (also when their output is presented). |
86 |
| - Do not use it for bash scripts with comments. |
87 |
| - You can find a more detailed description here: https://github.com/localstack/docs/pull/55. |
88 |
| - If needed, you can also [highlight a specific line](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences). |
89 |
| -- **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). |
90 |
| - You can either use `ref` or `relref`, the point is to have compile time internal-link checks (which works for both). |
91 |
| - |
92 |
| - ```text |
93 |
| - # Do this |
94 |
| - Configuration options are [here]({{< ref "/references/configuration" >}}) |
95 |
| -
|
96 |
| - # Don't do this |
97 |
| - Configuration options are [here](https://docs.localstack.cloud/references/configuration/) |
98 |
| - ``` |
99 |
| -- **Code snippets:** For snippets, make sure you indicate the programming/markup language so that proper syntax highlighting is used. |
100 |
| - Use `bash` only for Bash scripts, and use `text` for shell outputs or command examples. |
101 |
| - The full list of the supported languages [here](https://gohugo.io/content-management/syntax-highlighting/). |
102 |
| - If needed, you can also [highlight a specific line](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences) in the snippet. |
103 |
| -- **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. |
104 |
| - the cognito service docs). |
105 |
| - Then you can use the usual markdown syntax with a relative path (f.e.: ``). |
106 |
| - 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" >}}` |
107 |
| -- **Callouts:** Use these to make content stand out. |
108 |
| - The `callout` shortcode supports `note` (default), `tip` and `warning` levels. |
109 |
| - Use it like so: |
110 |
| - |
111 |
| - ```markdown |
112 |
| - {{< callout "warning" >}} |
113 |
| - This will make your computer halt and catch fire! |
114 |
| - {{< /callout >}} |
115 |
| - ``` |
116 |
| - |
117 |
| -## Troubleshooting |
118 |
| - |
119 |
| -This section covers common issues when working with LocalStack Docs: |
120 |
| - |
121 |
| -### Missing shortcodes |
122 |
| - |
123 |
| -Example error: |
124 |
| - |
125 |
| -```bash |
126 |
| -Start building sites … |
127 |
| -hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio |
128 |
| -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 |
129 |
| -Built in 45 ms |
130 |
| -``` |
131 |
| - |
132 |
| -1. Make sure to correctly clone and initialize the git submodules of this repo. |
133 |
| - For details see the section "[Clone the repo](#clone-the-repo)" above. |
134 |
| -2. Delete the Hugo Module cache using `hugo mod clean` or `make clean`. |
0 commit comments