Skip to content

Basic Editing

Jump to bottom
Luna edited this page Dec 10, 2019 · 4 revisions

This page explains the different elements of the editing and publishing process. You may find it more practical to simply follow the Editing Tutorial doc instead.

Note: If you are editing from the Command Line, make sure you've read the Installation & Setup, Files & Directories Guide, and Building & Serving the Site docs.

Basic Workflow Summary

The basic gyst of our editing workflow is as follows:

  1. Sync up with the remote servers
  2. Work on changes in the staging branch (or a sub-branch)
  3. Test our changes locally
  4. Test them remotely on the staging server
  5. Merge the staging branch into gh-pages
  6. Test the changes locally again
  7. Push them to the production site
  8. Admin only: If all looks good, then merge gh-pages into master and push to master

Luna: Remove the references to master?

Note: depending on which approach you follow in the Updating the Repo section below, some of the above steps may not apply to you.

Writing and Publishing Pages

Note: Please make sure you are always on the staging branch, unless otherwise indicated. Luna: Improve wording here to differentiate btwn git/terminal approach vs. pull requests

Markdown or HTML

Jekyll lets you write pages in either Markdown or HTML. You will probably find it easier to write pages in Markdown, unless you are already familiar with HTML. While HTML allows for greater control, it requires greater proficiency. Feel free to consult this Markdown Cheatsheet, or this HTML Cheatsheet.

You can use HTML in Markdown files, and vice-versa. The file extension determines what your main mode of writing will be. See the Editing Techniques doc for more info.

Metadata

Pages should include the following metadata at the top of the file (Note: the opening and close --- are essential for Jekyll to process the metadata correctly):

---
layout: default
class: contact
title: Contact
permalink: /contact/
---

For the layout field, you can use any of the layouts in the _layouts directory.

Collections

New pages go in their respective years or collections. For example, to add an Agenda page to the 2016 conference, you would create the agenda.md file in the get2016 folder (full path: get2016/agenda.md). To add a Sponsor to the 2015 site, you would create a file collections/_sponsors2015/sponsor_name.md. Luna: See if I can consolidate this paragraph with the one below the list.

Collections are a way to organize the subsections of the site's pages by content.

The site currently uses collections for the following:

  • 2012 Agenda
  • Awards Presenters
  • Awards
  • Breakout Leaders
  • Discussion Leaders
  • Expos
  • Judges
  • Labs
  • Media Partners
  • Moderators
  • Organizers
  • Prototypes
  • Speakers

Each collection folder is named in the following format: _speakers2016, _discussion-leaders2010, etc, and can be found in its relative collections folder. Example: for the 2013 Speakers, the folder will be collections/_speakers2013. For the 2013 Labs, the folder will be collections/labs2013.

People-Based Collections

All of the people-based collections (i.e. judges, leaders, moderators, organizers, presenters, prototypes, speakers) use the following format:

---
name: George Church
last: Church
image: /get2010/images/George-Church.jpg
---

George Church is Professor of Genetics, Harvard Medical School, Director of the Center for Computational Genetics. He is the founder of the Personal Genome Project (PGP), Chairman of PersonalGenomes.org, and PGP#1. He is the recipient of the Franklin Institute's 2011 Bower Award and Prize for Achievement in Science.

Note: the Judges collection also has an order field, so that judges appear in the proper order on the page. See if I can fix the page code so that the order field is no longer necessary

Awards

---
title: Diversity
image: /get2016/images/Diversity-120.jpg
alt: Diversity-120
---

This award recognizes excellence in promoting diversity in human research.

**Award Champion**: [Health Data Exploration Project (HDE)](http://hdexplore.calit2.net/), with support from the [Robert Wood Johnson Foundation](http://www.rwjf.org/)

Other Collection Types

Expos

---
name: C3-PRO
link: http://researchkit.org/blog.html#article-10
image: /get2016/images/C3_PRO.jpg
---

[C3-PRO](http://researchkit.org/blog.html#article-10): Consent, Contact, and Community framework for Patient Reported Outcomes is a "backend" connecting any ResearchKit app to a widely-used clinical research IT infrastructure called i2b2. C3-PRO relies FHIR (Fast Health Interoperability Resources). We are making C3-PRO available to the broader research community to be used with their ResearchKit apps and also integrating with ResearchStack.

Media Partners

---
name: hdexplore
image: /get2016/images/hde-long.jpg
facebook: http://hdexplore.calit2.net/news/
twitter: https://twitter.com/hdexplore
---

Updating the Repo

Once you're totally done with your page or collection/subsection [Luna: pick word], you have two options:

  1. Go to the PGP Global - Staging repo and manually add the pages with the editor there.
  2. Commit locally and then push to to the staging repo

Manually Adding the Pages or Pages on Github

  1. Finish the page on your computer, then navigate to the the PGP Global staging repo. The relevant links are:

Luna: I need to totally rewrite these links

Note: You must be on the staging branch. This has been accounted for in the above links already. Please make sure you see Branch: staging, as shown in the image below: Please do not add new pages to the gh-pages or master branches unless you are an admin.

GitHub Repo - Staging Branch Example

  1. Click create new file, then edit or copy & paste your page into the editor there. Scroll down to the bottom fill out the fields under Commit New File. Your commit message can be as simple as "My name: finished page 'page_name'". Note: Please include "Archives not regenerated" in the body of your commit message.

  2. Select "Create a new branch" and name it your-name-finished-pages. Then click "Propose new file". On the next screen, include any relevant notes, and then click Create Pull Request.

  3. Repeat this process for the Author page

That's it - you're done!!

Git Commit and Push the Changes

Add New Files

For any new files, type git add filename. You can add multiple files in a single command (ex: git add collections/_pages/page_name collections/_authors/aname.md).

Commit Your Changes

In your terminal, type git commit -am "Your commit message here". Commit messages should be less than 80 characters and follow a format such as Add Page Name and Author page, Add Page Name, Fix xyz on Page/Page Name, etc.

  • The -a flag stands for all (meaning commit all modified files)
  • The -m flag stands for message. This lets you type a simple one-liner message as the commit message. If you need to provide more details for whatever reason, then leave this off, and git will open up your text editor, so you can write a longer message.
  • You can also commit one file at a time by typing git commit filename -m "Your commit message here"

Merge Your Changes

If you've made a separate branch for your editing then run git checkout staging followed by git merge branch_name. Alternately push your new branch to the repo, and open a Pull Request (see Step 3 in the Manually Adding The Pages Or Pages On Github) section.

Push Your Changes to The Staging Repo

Type git push to push to the staging site. If you get an error it means you haven't set up your branch tracking properly. Type git push staging staging:gh-pages instead.

See the Installation & Setup and Using Git docs for additional info.

Clone this wiki locally