Portland Python Pirates Website
This is the home for the content files used to create the PDX Python Pirates website.
How to Contribute: Overview
The primary branch of this repository is named
- Fork this repo to your GitHub account.
- Clone to your local system and make content changes (see note on
- Run Hugo on your local system to verify your changes.
- 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-submodulesto fetch when cloning.
git clone --recurse-submodules firstname.lastname@example.org:GITHUB_USER/pythonpirates.org.git
If you missed the submodules in the initial clone you can update using the following:
git submodule update --init --recursive
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:
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/
-Dflag 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
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.
draftattribute 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
main before creating a new branch to make edits.
Check if you already have a remote defined for
git remote -v
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
main so it's caught up with the upstream main:
git checkout main git pull upstream main
Now you can create your branch and make your killer contribution:
git checkout -b my-awesome-website-contribution