The Push Redux is an implementation agnostic place to document things about Push and PushGP. It is hosted on Github Pages and is built using Pelican. The content is written in Markdown and then built into static HTML pages. All contributions are handled through GitHub Pull Requests.
This document aims to explain how to contribute to the Push Redux.
For this guide I will assume you know the basics of:
pip.Pelican is a static site generator that requires no database or server-side logic. This means that Pelican can take in content (written in Markdown) and output a static web page (HTML/css/js). This makes it ideal for creating a site on GitHub Pages.
To get started using Pelican, first you need Pelican! Use pip to get it.
pip install pelican markdown
Make sure you include markdown because we will use it.
Next, you must fork the push-redux GitHub repo. Once the repo is forked, clone the repo so you can edit your fork locally.
Once the repo is cloned, cd into the project folder. You should see the following folders and files.
content/
docs/
themes/
Makefile
pelicanconf.py
publishconf.py
There will likely be other files and folders in the push-redux repo, but won't need to talk about them in this guide.
The content/ folder contains all of the Markdown files that make up the pages in the final web page.
The docs/ folder is where Github Pages looks for static web pages to display when a browser goes to erp12.github.io/push-redux/. This means that Pelican will place the HTML/css/js/etc in the docs/ folder when we build our static website.
The themes/ folder contains folders of themes that determine the layout and style of the Push Redux website. Pelican uses the Jinja template-ing engine to create themes. Modifying the contents of the themes/ folder will only be necessary if you intend to modify the sites layout and style.
pelicanconf.py and publishconf.py are python modules. They behave like simple settings files with Python syntax. These files will likely be the only Python coding required to contribute to the Push Redux, and it is very unlikely any modifications to these files will be needed.
The Makefile assists in building the Pelican project into a static site. See the next section.
To preview the site locally, simply run the following command:
pelican path/to/push-redux/content -o path/to/push-redux/docs -s path/to/push-redux/pelicanconf.py
If you are on a Unix machine, this is made easier by the Makefile. Simply run make html.
Be sure to check the console for any errors that occured wile building the site.
Now open the path/to/push-redux/docs/index.html file in your web browser to preview your changes.
BE WARNED: As you navigate between pages, you may find yourself having to click on the
index.htmlfile for the folder you are in. This is normal. GitHub Pages displays theindex.htmlfile in the current directory by default. Once your changes go live on the main repository, this will not happen anymore.
After you make your changes locally, and have previewed them to ensure they look as intended, you will need to push these changes to your GitHub fork.
Once your changes are have been pushed to your GitHub fork, open a pull request between your fork and the main push-redux repository. This can be done from the GitHub website. More information about pull requests can be found here and here.
One the pull request has been submitted, your changes will be reviewed and (most likely) accepted. Then your changes will be visible on the Push Redux GitHub Pages site!
In Pelican projects, you can find the Markdown (.md) files for every pages in the path/to/push-redux/content/pages/ folder. Every time the Pelican site is built, the Markdown files in the content/ and content/pages/ folders in converted into HTML files in the docs/ folder.
To modify the text of a page, simply change the corresponding markdown file found in the content/pages/ folder.
When the Push Redux site is built, Pelican looks for any .md files in the content/pages/ folder and converts them to HTML pages on the site. Thus, in order to make a new page on the Push Redux site, simply add a new Markdown file (with .md extension) in the content/pages/ folder.
At the top of the Markdown file, you must enter some metadata. The metadata for this page looks like this:
Title: How to Contribute to the Push Redux
The Title value will be the title of the page. This will appear in large print at the top of the page. The Title value is the only metadata value that is required for pages. There are more metadata values that could be set, but they will have no visible effect.
Notice the URL of this page: pages/contributing/index.html. The filename of the Markdown file this page was generated from is named contributing.md. When you create your Markdown file, be sure to give it a name that is 1) not the same as any other page and 2) the path you would like Pelican to place your page on.
Below the metadata (Title), you may write the content of the page.
The style of the Push Redux site is determined by the style-sheets included in the theme. The Push Redux site uses the theme found in the themes/push-redux-theme/ folder. This theme is modified version of the theme found in the themes/tuxlite_zf/ folder.
Unlike the tuxlite_zf theme, the push-redux-theme uses a style-sheet that customizes style components. This style sheet is located at themes/push-redux-theme/static/css/push-style.css.
If you modify the push-style.css file, you can change the style of the Push Redux site.
You can also add more css, js, and images to the themes/push-redux-theme/static/ folder to change the style of the theme. If you do this, it is likely you will need to modify the HTML of the theme. (ie. Link a new style sheet or load a new javascript script). This will require changes to the Jinja theme files, which is explained in the next section.
Pelican uses the Jinja theme engine to manage the theme of the website. If you look in the themes/push-redux-theme folder you should see two folders: static/ and templates/. As mentioned in the previous section, the static/ folder is where you put all of the external resources that will be included in the HTML of the theme. Javacript files, css style sheets, image files, etc should all be placed in the static/ folder.
The templates/ folder contains many .html files. These files are Jinja templates, which define how various HTML components of the Pelican site should be generated.
The base.html file contains the <head> that will be included in every generated HTML file, the navbar definition, and the sidebar definition. If you intend on adding your own scripts/style sheets, you will have to modify this file.
For larger changes to the push-redux-theme you will have to consult the Jinja documentation.
Modifying the sidebar links is done by modifying values in the pelicanconf.py file. In the pelicanconf.py file, there is a variable called LINKS which is defined as nested tuples. Each tuple consists of 1) the text that should appear in the sidebar and 2) the URL which the link should point to. Modify the LINKS tuple to change and rebuild the site to change the sidebar links.
Generally speaking, if you insert HTML into your Markdown files it will be preserved when the site is built. This can be used to put anchors throughout your Markdown document. This allows other pages to link directly to the location on the page which the achor is placed.
For example, in the Markdown file that creates this page the Tips and Tricks section looks like this:
<a name="tips_and_tricks"></a>
#### Tips and Tricks
The <a> tag with the name attribute is an anchor. Now we can link to this anchor like this:
<a href="path/to/contributing/index.html#tips_and_tricks">
or
[text here](path/to/contributing/index.html#tips_and_tricks)
To link to an anchor found in the same page you are linking from, simply do the following:
[text here](#tips_and_tricks)
To see it in action this link will bring you to the Getting Set Up section at the top of the page.