Tips on maintaining this website

This website uses Jekyll to automatically render a combination of HTML and Markdown pages.

The final rendering is based on a combination of the following:

• content in individual Markdown or HTML files
• data in structured data files that is processed onto pages
• layout templates
• CSS for style

For any given page, there should be a Markdown or HTML page in the repository that forms the basis of that page. At the top of the file, there will be metadata that helps understand how that page is rendered. Most important is the layout tag which indicates the layout file that is used to render that page.

In it's simplest form, the layout file will simply convert the markdown to HTML and render it as is. More complex layout files will process data into rendered HTML.

For example, the file that lists skills in the manual uses the desc_list template to process data from a file. The data file is specified using the data tag, and its data is processed into an HTML description list with an optional list of links. The layout file uses CSS tags to invoke different styles that are applied universally across the site, and included from a hierarchy of CSS files.

In order to edit this file, you can:

• edit the content in the file itself: community/manual/skills.md
• edit the desc_list layout file: _layouts/desc_list.html
• edit the data in the data file: _data/skilss.yml
• (advanced) edit the CSS style files: _sass/_variables.scss or _sass/_bootstrap_customization.scss

Local testing of file rendering

In order to test the rendering of the files, you can run a local Jekyll server using a docker image.

prompt%> cd <path-to-new-website-repo>

prompt%> docker run --rm --volume="$PWD:/srv/jekyll" --volume="$PWD/vendor/bundle:/usr/local/bundle" -p 4000:4000  jekyll/jekyll  jekyll serve

This will launch a local server that will constantly monitor the files and re-render them each time the files change. It may take some time to install jekyll's internal dependencies. (see here for more.)

You can then load the URL localhost:4000 in a browser on your native system.

Add yourself to the CNERG website

1. Before you start:

• If you are not familiar with git and version control, consider this tutorial
• Make sure you already have git installed on your computer
• You may also want to refer to this summary of git workflows
• Create a github account, if you don’t already have one.

2. Clone a copy of the CNERG website repository

   1. Fork the CNERG website repository. This can be done by clicking the “Fork” button in the top-right corner. Forking means you have your own version of the repository where you can make changes that won’t be reflected in the main repository.

   2. Clone your fork. This will download your fork to a directory on your local machine.

   git clone [email protected]:<github_username>/cnerg.github.com
   

   3. Move into the newly created cnerg.github.com folder

   cd cnerg.github.com
   

3. Make a branch to isolate the changes

   1. Create a new branch where you will make the changes. (It doesn’t have to be called “add_myself”, that’s just an example.)

   git branch add_myself
   

   2. Switch to your new branch.

   git checkout add_myself
   

   3. Note that steps 4 and 5 can be completed simultaneously with

   git checkout -b add_myself
   

4. Add the Data/Files for your Page

   1. Descend into the community/people directory and make a directory for yourself (mkdir ). Most people use initials, but you can use anything that is unique

   cd community/people
   mkdir <initials>
   

   2. Change to that directory

   cd <initials>
   

   3. Add a photo of yourself by copying a file into this directory

   cp <path to image> .
   

   4. Add an index.md file - it’s easiest to copy one from someone else. Either

   touch index.md
   

   or

   cp <path to someone elses index.md> .
   

   5. Edit the index.md file by changing the data in the header
      • You can delete any that are not relevant
      • Make sure the image data refers to the photo you have copied in to this directory

5. Add Your Data to the Site Data

   1. Descend into the _data directory

   cd ../../../_data
   

   and edit people.yml

   2. Create an entry for yourself in the correct group - it’s easiest to just copy someone else’s entry
   3. Update the data for you
      • The url should be the name of the directory you created above
      • The image should be the name of the file you copied into that directory above

6. Test Your Addition

   1. You can test your addition by running the docker image referenced in the README:

     cd <path-to-website-repo>
   

   (e.g. cd .. if in the _data directory)

   docker run --rm --volume="${PWD}:/srv/jekyll" --volume="${PWD}/vendor/bundle:/usr/local/bundle" -p 4000:4000 jekyll/jekyll jekyll serve
   

   2. Review your changes in a web browser at localhost:4000. If you make a change, you can refresh the browser and it should auto update (a few seconds after you save the changes)

7. Save your changes

   1. Once you feel it looks correct and the way you want it, add and commit your changes. This will save your changes to your local clone of your fork. It is often very useful to use git status, which will give you information like which files have been modified but are not staged for commit, which files have been modified and have been staged for commit (i.e. they have been git added), and whether you have commits in your clone that are not yet reflected in your github fork or vice versa.

   git add <new_or_modified_files>
   git commit -m “Added <my_name>”
   

   2. Push your new branch to your github fork. If your fork already contains the branch and you are only updating it with new commits, then git push by itself is sufficient.

   git push -u origin add_myself
   

8. Request that your changes be added to the official website

   1. Create a pull request (PR) between the branch on your fork and the “source” branch in the main repo. This can be done by using a web browser to navigate to your new branch on your fork and clicking “Pull request”.

   It will probably look like this:

   But you may need to go through the “Contribute” menu to start a PR:

   NOTE: you must be on the new branch for the contribute menu to pop up with a PR (step 1 in the picture)

   This will allow other users to review the changes you made and make comments, request changes, or approve your changes. Once your PR has been created, you should be able to see it here.

   2. Once you and one or more reviewers are satisfied with your changes, someone with write access will merge your branch into the main repo. This only updates the .rst files; it doesn’t update the rendered html. Someone will also need to regenerate the rendered .html before your changes will be reflected in the actual website.

   3. Once this is done, you’ll be able to find yourself on the staff and students page of the website!

Boostrap 4 Github Pages

A Bootstrap 4 start up project for Github Pages and Jekyll.

• A full Bootstrap 4 theme usable both on Github Pages and with a standalone Jekyll.
• Recompiles Bootstrap from SCSS files, which allows to customize Bootstrap's variables and use Bootstrap themes.
• Full support of Bootstrap's JavaScript plugins.
• Supports all features of Github Pages and Jekyll.

See the website for demonstration and documentation.

Contribution

See the contribution guide.

License

See the license file.