Portland Python Pirates Website

This is the home for the content files used to create the PDX Python Pirates website.

The content is written in Markdown and rendered to static HTML using Hugo, a static site generation tool.

How to Contribute: Overview

1. Fork this repo to your GitHub account.
2. Clone to your local system and make content changes (see note on git submodules below)
3. Run Hugo on your local system to verify your changes.
4. Commit changes to your fork and open a pull request.

Please note this repository make use of git submodules which requires an extra flag --recurse-submodules to fetch when cloning.

git clone --recurse-submodules [email protected]:GITHUB_USER/pythonpirates.org.git

If you missed the submodules in the initial clone you can update using the following:

git submodule update --init --recurse

Verify Changes Locally

When making edits it is recommended you run a local installation of Hugo to verify the pages render as expected.

Fortunately, Hugo is not difficult to install and run.

See the official Hugo docs to:

• Install Hugo for your operating system.
• Verify the executable is found in your PATH.

Once installed, start hugo from a command prompt with the project root as the current directory.

# repo was cloned to directory 'pythonpirates.org'
cd /path/to/git-projects/pythonpirates.org

hugo server -D

This starts up a Hugo server listening on http://localhost:1313/

The -D flag is optional and tells Hugo to include pages marked as "draft" status.

Make your edits & when finished:

• commit your changes locally... you made a branch, right? ;-)
• push to your fork on GitHub
• open a pull request
  A preview of the site will be linked from the pull request ticket
• notify someone in Slack to review the change and merge the pull request

A Note on Front Matter and Drafts

Each content page starts with a section called front matter. This is easily identified at the top of the file within a section fenced by --- or +++.

The front matter serves as a place to record metadata for the page such as author, background image, keyword tags, and more. Most fields are self explanatory.

Front matter is also the place where a page is marked as a draft. This is notable because Hugo does not publish pages marked as draft to our website.

You can override this behavior in your local installation by running hugo with the -D flag. This is useful when authoring content that is not quite ready to be published but you want to check the rendered result.

Example front matter:

---
# comments starting with '#' are allowed in front matter
title: "Use Python to Take Over the World"
date:  2018-11-22
# page is marked as a draft and will not publish to the live site
draft: true
---

When you are ready to publish the page, update the value draft: false, or delete the draft attribute line.

The draft attribute is the first thing to check if a page isn't showing up on the website that you expect.

Updating Your Clone

Your cloned copy can easily fall out of date when regular updates are being merged into the main website repository. Because of this possibility, it's a good practice to update your local copy of master before creating a new branch to make edits.

Check if you already have a remote defined for upstream:

git remote -v

If upstream isn't in the list of remotes then add it:

git add remote upstream https://github.com/PDXPythonPirates/pythonpirates.org.git

Update your local master so it's caught up with the upstream master:

git checkout master
git pull upstream master

Now you can create your branch and make your killer contribution:

git checkout -b my-awesome-website-contribution