phillycommunitywireless / phillycommunitywireless

Website for the Philly Community Wireless Project

phillycommunitywireless.org

Source code for the Philly Community Wireless website, phillycommunitywireless.org (or pcw.fi). The site is built using the Hugo static site generator and hosted with GitHub Pages.

Contents
    Theme
    Local development

Theme

The site's theme is a fork of gohugo-theme-ananke with major modifications.

Custom CSS

Custom CSS lives in /assets/pcw-hugo-theme/css/custom.css

Segments

This theme supports a segments front matter parameter for all normal pages, which allows for composing layouts from "stackable components". The segments param is a YAML list of objects, each of which will correspond to one of these components. Each type of segment uses a pre-written HTML template to render a component, like a full-width photo, a video, or a call-to-action, to the page it's used on. Segments are all full-width and can usually be customized right from the YAML.

Example

Here is an example of some typical Hugo front matter, along with the segments param. This would render a single full-width image followed by a volunteering call-to-action:

---
title: Home
segments:
  - template: image
    src: images/antenna.jpg
    alt: An image of an antenna mounted on a brick wall.
  - template: call-to-action
    text: Volunteer!
    link:
      href: https://example.com/volunteer
      text: Get involved
---

Segment types

A segment consists of a template string that determines which HTML template is used, as well as a series of other mandatory and optional params to serve as props/options for the component. These are the currently supported types:

markdown

A section of markdown text.

- template: markdown
  url: The url of the markdown file, relative to your content directory.
  # Optional
  class: CSS classes (space separated) to add to the container element. Useful for e.g. font settings, background color, etc.

heading

A simple full-width heading (h1).

- template: heading
  text: The text to display in the heading.
  # Optional
  class: Classes to add to the h1 element

divider

A dotted line to divide sections visually.

- template: divider
  narrow: false # Set `true` to use a narrower divider
  # Optional
  class: Classes to add to the div element

image

A full-width responsive image.

- template: image
  src: Image source
  alt: Alt text
  # Optional
  class: Classes to add to the img element.

video

A full-width responsive embedded video.

- template: image
  src: Image source
  title: Title of the video (mandatory)
  # Optional
  class: Classes to add to the container element.

call-to-action

A highlighted section with (optionally) a header and some text, followed by a big visible link.

- template: call-to-action
  text: Text to display above the link. Markdown can be used here (but not shortcodes).
  link:
    href: The URL the link should point to.
    text: The text to display on the link.
    # Optional
    class: Classes to add to the link/button element
  # Optional
  heading: A heading above the text.
  class: Classes to add to the container element.

call-to-action-image

Same as above, but split vertically with an image on the right side.

- template: call-to-action-image
  # Same as above, with the addition of:
  image:
    src: Image source
    alt: Image alt text
    # Optional 
    class: Classes to add to the img element
  # Optional
  reverse: false # Set to `true` to display the image on the left instead.

icons

A responsive layout featuring three font-awesome icons with optional text labels. Supports Font Awesome 5 icons.

- template: icons
  icons:
    - icon: fas fa-example-1 # The Font Awesome class for your icon.
      text: Label text 1
    - icon: fas fa-example-2
      text: Label text 2
    - icon: fas fa-example-3
      text: Label text 3
  # Optional
  class: Classes to add to the container element.

Adding new segment templates

You can create a new segment template by creating a <type-name>.html file in the theme/pcw-hugo-theme/layouts/partials/segments directory. This template will automatically be used to render segments with this title. The context passed to the partial will be the segment object from the YAML (you can access the global site variable as site).

Local development

Development server

• To start the server: docker-compose up -d
• To stop the server: docker-compose down
• Server is at http://localhost:1337.

Deploy a staging site for demos

• Install hugo and surge.
• From the project root directory, run hugo && surge public --domain pcw-staging.surge.sh.
• The staging site will be deployed to https://pcw-staging.surge.sh.

Alternatively, add a file named CNAME with the following contents to the /static directory:

pcw-staging.surge.sh

This will remove the need for the --domain pcw-staging.surge.sh option, and hugo && surge public will just work.

phillycommunitywireless's Issues

Reorganize the FAQ to prioritize most important & common questions

We should make the most important and commonly-requested information easy to access quickly. The copy should also be edited to remove unnecessary and duplicated information.

Good questions to prioritize:

• Who are we?
• How does it work?
• Is it secure / user data questions
• Why is it free? Will it always be free? Etc

Site content

We should start thinking about what content should go on the site as well as the format it should take.

One thought I had was to provide weekly updates in the form of summaries of the meeting notes, but maybe that would be too much.... minutia? Either way, as it stands, I feel like visitors to the site may get the feeling that either there's no progress being made or that the project is abandoned (like with the philly mesh project).

Note: treat this less as an "issue" and more as an action item

change github pages source branch

I was experimenting with automating the build and deploy process for this site (see 8ba2070, d79487c, 889ac4e), and part of the process is to deploy to a branch other than master--- gh-pages.

@gwijthoff can you change the source branch to gh-pages? I don't have admin access to this repo, so I can't change the setting myself 😖

Documentation

I think it would be useful to provide a how-to guide here in the repository so that anyone who wants to can publish content. This document might look something like this:

• quick guide
  • i.e. how to add/edit content using the GitHub UI
• advanced guide
  • forking(?)
  • installing git/hugo
  • adding/editing content
  • testing locally
  • pushing/making PR

Prevent CI/CD workflow from deploying on PR CI builds

as seen in #15 the github action workflow fails because the PR author (dependabot) doesn't have proper permissions to push to the repo.

this works in our favour for the moment, because pull request builds shouldn't be deployed over the version from master. however, if someone with permissions were to make a PR, the workflow would successfully deploy.

the fix should be fairly straightforward, and will just require a minor rework of our github action workflow so that the separate steps (build and deploy) are only triggered both at once on master, otherwise run build only.

Accessibility improvements

We meant to do an accessibility audit of our website. I imagine any issues are minor, but this is a good time to think through any revisions to design principles as we build out the site to be more public facing. @timtraversy is this something that you would be interested in looking into?

Add authentication to api browser

• Fork docker-UnifiBrowser
• edit config/users-template.php to add an example user
• ... ?

Redesign Hugo site for simplicity

@timtraversy @addiebarron opening a ticket regarding our conversation to simplify the site for ongoing editing and updating. Let's aim to have scoped out what we can do by mid-August

Add focus indicators to nav items and links

We need better focus indicators for our nav items and links. We're trying to use the Tachyons CSS library for styles as much as possible, but it doesn't have a lot of options for focus, so this will need to be added in a CSS file. Standardizing our "extra CSS" location would be a useful byproduct of this!

Deque's guide on focus indicators is a great place to start for preparation.

Add a section for partner org logos to homepage

Alex requested this in Slack.

A section in the homepage would probably have to be hard-coded into the theme (themes/pcw-hugo-theme), the same way the "Contact us" section currently is. It would be great if it was customizable via a config file or front matter, probably using a Hugo menu.

Anyone can take a crack at this and make a PR, but if not I'll probably get to it in the next few weeks!

page build failure

Hey @HotelCalifornia — I updated our member page with this commit, and now it looks like we're getting a page build failure with the gh-actions process you set up. See here. Any suggestions? Maybe @TGNYC has thoughts?

install dependabot

@HotelCalifornia could we avoid this happening in the future by using Dependabot?

Originally posted by @hawc2 in #9 (comment)