Contribute

This section provides guidance and resources on how to contribute to the IoT Atlas. It covers:

  • Guidelines for content creation using Hugo
  • Style guide
  • Templates for different content types
  • Process for creating and validating content locally

By following the same set of guidelines, this helps ensure the consistency of the Atlas from page to page.

Authoring new content

When creating new content, use the follow guidance:

  1. A customized Hugo Learn Theme is the basis for this site. Unless extended or called out below, all Learn Theme design content and shortcodes can be used. Additional features are listed below and shown in the templates folder, or in the kitchen sink example that demonstrates all features.
  2. If creating similar content that already exists, use an existing page as the basis for headings, style, and approach. You can also review the example style templates in this section.
  3. Test content changes locally and only submit a pull request once the validation passes successfully. Pull requests will not be merged with broken links or invalid Hugo references/code.

Following the steps below will ensure that any contetn pr 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.

Pre-requisites

To reduce installing dependencies, the main 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.

Testing Process

  1. Once you are ready to start creating content, run the developer mode which will run Hugo locally in fast render mode.

    ./make_hugo.sh -d
    
  2. This starts a local server on port 1313 serving the rendered content. The default URL is http://localhost:1313 and will show most content with the exception of rendered images from AsciiDoc or PlantUML. To see this content, fully generate the content and view locally from a web browser opening src/hugo/public/index.html.

  3. 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.

Once you have completed development, run ./make_hugo.sh without any arguments to have it fully generate and validate the content. Once successful, you can commit and perform a pull requests.

Hugo and Theme Details

This sections covers structure and use of more complex pages and use of short codes.

Bundle Resources

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.