|
| 1 | +LocalStack Docs |
| 2 | +===================== |
| 3 | + |
| 4 | +Repository for [docs.localstack.cloud](https://docs.localstack.cloud). |
| 5 | + |
| 6 | + |
| 7 | +Getting Started |
| 8 | +----------- |
| 9 | + |
| 10 | +### Basics |
| 11 | +LocalStack Docs is using the following technology stack: |
| 12 | +- [Hugo](https://gohugo.io) to generate the static site. |
| 13 | +- [Docsy](https://docsy.dev) as a theme for Hugo. |
| 14 | +- [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 | + |
| 16 | + |
| 17 | +### Clone the repo |
| 18 | +Clone this repository and initialize the Git submodules recursively (`themes/docsy` is a submodule that again has submodules for vendored assets like fontawesome). |
| 19 | + |
| 20 | + git clone --recurse-submodules --depth 1 [email protected]:localstack/docs.git |
| 21 | + |
| 22 | +This performs a shallow clone, which leads to only the main branch being configured for your remote. |
| 23 | +To be able to pull/push from/to all branches, please run: |
| 24 | + |
| 25 | + git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" && git fetch |
| 26 | + |
| 27 | +or: |
| 28 | + |
| 29 | + git clone [email protected]:localstack/docs.git |
| 30 | + cd docs |
| 31 | + git submodule update --init --recursive |
| 32 | + |
| 33 | +### Install Hugo |
| 34 | +LocalStack Docs is based on the [Hugo static site generator](https://gohugo.io). |
| 35 | + |
| 36 | +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. |
| 37 | +You also need to make sure that `go` is installed in order to run hugo scripts. |
| 38 | + |
| 39 | +### Run locally |
| 40 | +Once you have Hugo installed, you can start your local server with the following command: |
| 41 | + |
| 42 | + hugo serve |
| 43 | + |
| 44 | +or run in developer mode with automatic reload: |
| 45 | + |
| 46 | + hugo serve --watch=true --disableFastRender -D |
| 47 | + |
| 48 | +Once the server is started, the locally served Docs are available at http://localhost:1313. |
| 49 | + |
| 50 | +### Writing content |
| 51 | +The whole site is generated with Hugo, a powerful static-site generator. |
| 52 | + |
| 53 | +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. |
| 54 | + |
| 55 | +Make sure to follow the best practices below when contributing content. |
| 56 | + |
| 57 | +#### Updating developer hub applications |
| 58 | +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. |
| 59 | + |
| 60 | +Example usage in the project root: |
| 61 | + |
| 62 | + node scripts/create-applications.js |
| 63 | + |
| 64 | +## Best Practices |
| 65 | + |
| 66 | +Please follow these best practices when writing documentation in this repository: |
| 67 | +- 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 |
| 68 | +- 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). |
| 69 | + You can either use `ref` or `relref`, the point is to have compile time internal-link checks (which works for both). |
| 70 | +- Stick to markdown if possible. |
| 71 | +- Use one line for each sentence in markdown. |
| 72 | + 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. |
| 73 | +- For snippets, define the correct syntax highlighting. |
| 74 | + Here's a list of the supported languages: |
| 75 | + https://gohugo.io/content-management/syntax-highlighting/ |
| 76 | +- 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 |
| 77 | + - This is also supported by the `command` shortcode! |
| 78 | +- Handling images can be a bit tedious with Hugo. |
| 79 | + 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). |
| 80 | + |
| 81 | + Then you can use the usual markdown syntax with a relative path (f.e.: |
| 82 | + ``). |
| 83 | + |
| 84 | + If you want to resize the image, use the `figure` or `img` shortcode. For example: |
| 85 | + `{{< img src="cockpit-init-check.png" class="img-fluid shadow rounded" width="150px" >}}` |
| 86 | + |
| 87 | +PS.: Feel free to add more best practices here. |
| 88 | + |
| 89 | +## Troubleshooting |
| 90 | +This section covers common issues when working with LocalStack Docs: |
| 91 | + |
| 92 | +### Missing shortcodes |
| 93 | +Example error: |
| 94 | +``` |
| 95 | +Start building sites … |
| 96 | +hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio |
| 97 | +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 |
| 98 | +Built in 45 ms |
| 99 | +``` |
| 100 | + |
| 101 | +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. |
| 102 | +2. Delete the Hugo Module cache using `hugo mod clean` or `make clean`. |
0 commit comments