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

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

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

This site uses Hugo's figure shortcode. It's highly recommended to use figure rather than simple images via Markdown (i.e. ![]()), so that images can be automatically sized and properly styled. Non-figure images may not display in a consistent manner.

To insert a figure into a post, paste the following example text directly into the markdown file:

{{< figure src="/images/elephant.jpg" title="An elephant at sunset" >}}

When the site is built, it will be rendered as follows:

<figure>
  <img src="elephant.jpg">
  <figcaption><h4>An elephant at sunset</h4></figcaption>
</figure>

We've also added an additional css class figure-center for centering images/captions in the viewport

{{< figure class="figure-center" src="/images/elephant.jpg" title="An elephant at sunset" >}}

Which will render as so:

<figure class="figure-center">
  <img src="elephant.jpg">
  <figcaption><h4>An elephant at sunset</h4></figcaption>
</figure>

You can add image captions and credits using the figure shortcode's parameters caption, attr, and attrlink. When adding captions/credits, you will most likely want to use the figure-center class as well to ensure the text and image are properly aligned.

Additionally, the caption parameter will render any markdown in the argument - for example, caption="*some caption here...*" will render italicized - e.g, some caption here.

*An attr parameter with no/an empty attrlink will have no link styling - to fix this, just use '#' for the value of attrlink - e.g, attrlink='#' *

Here's an example use for a photo with attribution:

{{< figure class="figure-center" src="/images/treepr.jpg" alt="A tree with the Puerto Rican flag painted on the bottom branches." caption="A tree at NSNP." attr="Photo by me." attrlink="http://example.com/" >}}

The figure shortcode can use the following named parameters:

src

URL of the image to be displayed.

link

If the image needs to be hyperlinked, URL of the destination.

target

Optional target attribute for the URL if link parameter is set.

rel

Optional rel attribute for the URL if link parameter is set.

alt

Alternate text for the image if the image cannot be displayed.

title

Image title.

caption

Image caption. Markdown within the value of caption will be rendered.

class

class attribute of the HTML figure tag.

height

height attribute of the image.

width

width attribute of the image.

loading

loading attribute of the image.

attr

Image attribution text. Markdown within the value of attr will be rendered.

attrlink

If the attribution text needs to be hyperlinked, URL of the destination.

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.

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

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:

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.

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

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

A full-width responsive image.

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

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.

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.

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.

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.

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

After navigating to static/images, you can add funder logos in PNG, JPG/JPEG, or SVG formats to the folder titled funders.

Then, you can create a new "funder card" on the Funders page (located in content/en/funders.md or content/es/funders.md) by following the format below and pasting it to the top of the funders.md file below the 2nd --- divider:

(Parentheses here represent what should be replaced, for example: (Organization Name) -> PCW.)

<div class="funder-card">
    <img alt="(Organization Name)" src="/images/funders/(what you saved the logo as)"/>
    <div class="funder-desc">
        (Grant Title), <a href="(organization's website)">(Organization Name)</a>, (Year)
    </div>
</div>

or, if the grant has a logo/website:

<div class="funder-card">
    <img alt="(Grant Title)" src="/images/funders/(what you saved the logo as)"/>
    <div class="funder-desc">
        <a href="(grant's website)">(Grant Title)</a>, (Organization Name), (Year)
    </div>
</div>

• To start the server: docker-compose up -d
• To stop the server: docker-compose down
• Server is at http://localhost:1313.
  • NOTE - Experienced an issue on Windows where hot reloading did not work and viewing changes required restarting the container. Fixed by adding --poll 700ms to server -D in compose file and rebuilding container - see Forums

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