This section provides guidance and resources on how to contribute to the IoT Atlas. It covers:
Following these guidelines helps ensure the consistency of the Atlas from page to page.
When creating new content, use the follow guidance:
Following the steps below will ensure that any content or changes you make can be tested and validated prior to submitted a pull request. If you have any questions, please review and ask questions in the discussions section of the GitHub repository.
To minimize installing local dependencies on your system, the only requirement is to have Docker installed locally. Also, the make_hugo.sh
script is Linux/macOS (well, bash) specific, so for Microsoft Windows the commands would need to reviewed and changed. Setup your local environment by following these steps:
iot-atlas/src
directory, run ./make_hugo.sh -d
to start in local development mode.The first time doing this will locally build the docker container which will take 5-15 minutes. After that, the local temporary/hugo-ubuntu
will be used to run hugo in a container
This final step starts a local server on port 1313 serving the rendered content. Every time you make and save a change, the local server will re-render and trigger your local browser to reload the page. If changes are not reflected, enter CTRL+C
to stop the process and start ./make_hugo.sh -d
again. This can help when moving content or working with new directories
Once you are happy with the new content, run ./make_hugo.sh -v
, which will validate all the content is properly formatted, and that if you included any hyperlinks that they are valid. If errors are returned, correct and re-run.
When the message ****** Validation completed successfully, is returned, validation is complete.
From GitHub, use the pull request process to create a pull request (PR) to the aws/iot-atlas
repository. This will start a validation process under the open pull requests again, and provide a message if the PR can be merged. If there are errors (red ❌ next to your PR), review the error, correct in your forked repository, then commit the changes.
Once validation has completed, an IoT Atlas maintainer will review and either merge the content, or request changes or ask clarifying questions.
Once merged and content is live, you can delete the forked repository.
This section covers both style and technical approaches to creating new content.
This sections covers structure and use of more complex pages and use of short codes. This site is based off of the Hugo Learn Theme. All content and shortcodes for that theme are available for use here.
If there are diagrams or other images related to your content, include and reference those from within the same directory as a Page Bundle. For instance, a new Pattern called Foo would be structured like this:
Pattern/
_index.md
Foo/
_index.md
img1.png
img2.png
Referencing images within Pattern/Foo/_index.md
would look like this in markdown:
Lorem ipsum dolor sit amet, consectetur adipiscing elit...
[Image One](img1.png)
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.