Making Technical Contributions

Developing this site locally

If you intend to make a technical contribution to the underlying templates for this site, please make sure you follow the best practices outlined here.

(If you are looking to make a contribution or edit to the content of a lesson, see our contributor guidelines instead.)

These best practices assume that you are generally familiar with git, GitHub, and Jekyll.

• GitHub lesson
• Jekyll lesson

Forking the repository

We welcome contributions from everyone via Pull Request.

NOTE FOR CURRENT EDITORS: If you are already added as collaborators to this repository and are able to push commits directly, please feel free to commit minor changes (typo fixes etc.) directly. However, major additions involving moving or erasing files, editing Jekyll layouts or includes, or making structural changes to any YAML files, should be done via PR, so that another member of the team can review them before merging.

If you have any questions, create an issue and tag @mdlincoln.

Setting up a GitHub pages development environment

This site is built via Jekyll, using GitHub Pages as a hosting service. This means that all code in this GitHub repo is processed by GitHub servers to produce the HTML pages that readers see. If you want to preview what this generated site looks like on your own computer, you need to make sure you are using the same versions of Jekyll and its dependencies that GitHub does.

1. Set up Jekyll dependencies.
2. Fork the programming historian repository, and clone that fork to your local machine.
3. Ensure you have the "bundler" gem installed by running the command:

gem install bundler

4. cd into your clone of the PH repository, and install all the necessary dependencies with the command bundle install
5. Run bundle exec jekyll serve --watch to generate the site and start a local webserver. You can then preview the local version of the site by going to http://localhost:4000 in your web browser.

Best practices

Modifying baseurl in _config.yml

If you only need to preview your modifications on your own local machine, then you do not need to make any edits to _config.yml

However, you may want to push changes on to your online fork of the repository in order to create a live preview of your site shareable with others. If so you will need to temporarily add a baseurl value to _config.yml that matches the name of your forked repository. By default, your fork will be named jekyll. (If you changed that fork name in your own repo settings, you will need to put that name in baseurl instead.) Add the following line:

...
url: http://programminghistorian.org
basurl: jekyll
...

This will allow image links and redirect links to correctly point to your own published fork.

When submitting your pull request, be sure to remove the baseurl line from _config.yml

Filenames with special characters

Some files in this repository have non-ASCII characters such as ñ. Some earlier versions of Git and OS X get confused by these Unicode characters, and will register that a file has changed when, in fact, none has. These errors can be addressed by running the following command:

git config --global core.precomposeunicode true

When in doubt, do not git add files with special characters unless you are certain that you have created or modified them.

Check your PR status

We use Travis CI and htmlproofer to check that the site builds properly, and that none of the internal or external links on the site are broken. When you make a pull request (and, as a collaborator, if you push any commit), Travis will automatically try to build the site and check for problems. This usually takes a minute or two after you push your work online, and the results will appear as a green check mark, or a red X.

If your build has an error, you can click on the "Details" button to view the build logs. If you scroll to the bottom, you'll see an error report that may list URLs that led to unresponsive pages. If you can see how to fix it, then do! Otherwise, one of the PH editors will help resolve the problem. All build and broken-link errors must be fixed before any changes can be merged in to the site.