Skip to content

Latest commit

 

History

History
41 lines (23 loc) · 3.46 KB

README.md

File metadata and controls

41 lines (23 loc) · 3.46 KB
Raw

IoT Atlas Local Development

The IoT Atlas uses the Hugo framework for rendering the website. To ensure that all new or updated content is valid, a series of checks are performed on URL links, internal references, and spell-checking (for U.S. English at present) for common errors.

All of this is automated when a GitHub pull request is accepted. Failures will result in the updates not being applied and corrections required on the pull request.

Following the steps below will ensure that any 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, open a terminal window and change into the src/ directory, then start in developer mode which will run Hugo locally in fast render mode.

    cd src/
./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.

FAQ

I created content and see it in the src/hugo/public folder, but when I commit, this isn't being added to my forked repository, why?

This is by design by including the /src/hugo/public/* statement in the main .gitignore file.

As the website is statically generated through a build process and synched to an Amazon S3 bucket, there is no need to keep the content locally in the repository. It is only used for local validation of content.

When adding or changing the weight of an article, the left-side menu is not updating even with a browser refresh. How can I see the new structure?

Certain changes to content are not reflected with the fast render process. To see these, enter CTRL+C to stop the Hugo container process and run ./make_hugo.sh -d again, then refresh the browser.

When I run make_hugo.sh, it fails to build the docker image completely due to issues with newer versions of Golang always connecting to upstream proxy.gloang.org to fetch modules when the go get command is issued. How do I work arround this issue?*

Golang after version 1.13 will always try to fetch modules via upstream proxy proxy.golang.org. In some organizations, this domain is not accessible due to corporate security mandates. To bypass this, you can explicitly set the environment variable GOPROXY to the value direct. Execute the following command to run the local development environment as: GOPROXY=direct ./make_hugo.sh -d bypassing the Golang proxy setting.