alohasmask.org

This repository contains the source for alohamask.org.

Contributing to alohamask.org

There are generally two use cases for contributing to alohamask.org

1. To maintain and improve the original alohamask.org
2. To create your own local version of alohamask.org for your own community

We will examine both of these use cases.

Prerequisites

alohamask.org source

alohamask is freely hosted on GitHub under the terms of the MIT license.

The top-level directory alohamask.org contains readmes, scripts, licenses, git metadata, and a subdirectory alohamask.org. The actual static site as generated by hugo resides in alohamask.org/alohamask.org.

Whether you are improving the original alohamask.org or utilizing it as a template for your own local community, you will want to create a form of the repository into your own github account.

alohamask.org design

alohamask.org was designed using the hugo static site generator. hugo converts Markdown into static web pages. These web pages can easily be hosted with a general purpose webserver or on platforms such as GitHub Pages or AWS S3. Please install the latest version of hugo from their release page.

This implementation of alohamask.org is hosted on a micro AWS EC2 instance using the Caddy 2 server which provides automatic HTTPS through Let's Encrypt.

We are using the cupper theme to theme alohamask.org. The design is simple, clean, and most importantly, designed to be accessible. cupper also provides numerous shortcodes which provide capabilities beyond basic Markdown.

After reading through the hugo documentation and the cupper documentation, the best way to learn how hugo and cupper work is by going through cupper's exampleSite directory, which when compiled, produces this.

User feedback is currently handled by Google forms whose URLs are embedded in the source of the static site. We also utilize a shared Google account to track and organize responses and volunteers. Eventually, we may more to a more robust web framework and collect our own form values. Because we wanted to make this as accessible as possible and to get off the ground quickly, we decided a static site makes the most sense for the time being.

Some basic bits on interacting with hugo

Assuming you are using a terminal and your current working directory is the top-level directory of alohamask.org, you can take the following actions.

Run the hugo server in development mode. {{< cmd >}} hugo server --source alohamask.org {{< /cmd >}}

Compile the static site. The generated site will be available at alohamask.org/alohamask.org/public. {{< cmd >}} hugo --source alohamask.org {{< /cmd >}}

We've provided some helper shell scripts to make these tasks a little easier. Please run them from the top level directory.

• build.sh will compile your static site and place both the uncompressed and compressed compiled files in alohamask.org/build
• clean.sh will clean all build files and directories
• run_local.sh will run the hugo server in development mode

Some basic bits on adding or editing content

All content that can be edited or added to the site exists in either alohamask.org/alohamask.org/config.yaml or alohamask.org/alohamask.org/content/*. You shouldn't need to edit or add files anywhere else.

• Top level menu items are configured in alohamask.org/alohamask.org/config.yaml
• Each page must have the title and date top-level metadata
• If a post has images, create a new directory for the post that contains an index.md file and any images that will be used in the post.
• New "News Items" are automatically added the the list of news items on the news page.
• When in doubt, reference the exampleSite.

Maintaining or improving alohamask.org

If you would like to make edits or improvements to the original alohamask.org, follow these steps.

1. Create a new issue describing the change you would like to make
2. Fork the repository
3. Create a new branch named issue-[issue-number-from-step-1]
4. Make your changes and test locally
5. Commit your changes
6. Create a pull request

Creating your own local version of alohamask.org

We encourage other community led efforts to build off of our efforts to create your own version alohamask.org for your community. Please fork our repository and then make the requested changes specified in the next section.

Modifying alohamask.org for your own community

There are some changes that will need to be made if you would like to use this template for your own community.

1. Update the baseURL, title, and googleAnalytics fields in alohamask.org/alohamask.org/config.yaml
2. Change contact information provided in alohamask.org/alohamask.org/content/_index.md and alohamask.org/alohamask.org/content/about.md.
3. Create your own Google Forms for volunteers and mask requests. Please feel free to model your Google Forms off of ours.
4. Update the URLs to your Google Forms in alohamask.org/alohamask.org/content/requests.md and alohamask.org/alohamask.org/content/volunteer.md.
5. Delete all items in alohamask.org/alohamask.org/content/news/* except alohamask.org/alohamask.org/content/news/_index.md
6. Remove any references to latest news in alohamask.org/alohamask.org/content/_index.md

Serving your modified alohamask.org to your community

The details of hosting a static site are generally outside the scope of this discussion. There are essentially two strategies.

1. Use a traditional web server (Apache, nginx, Caddy, etc) to host the content
2. Use a service to host the content (GitHub Pages, Netlify, AWS S3, etc)

Confused by any of this?

Please create an issue and we will work to answer your questions.