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 elementA 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 elementA 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 700mstoserver -Dincomposefile and rebuilding container - see Forums
- NOTE - Experienced an issue on Windows where hot reloading did not work and viewing changes required restarting the container. Fixed by adding
- 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
CNAMEwith the following contents to the/staticdirectory:pcw-staging.surge.shThis will remove the need for the
--domain pcw-staging.surge.shoption, andhugo && surge publicwill just work.