Skip to content

Basic Editing

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

Many of the examples here are based on the PGP Global Docs, and will be updated to reflect the GET Conference site in the near future

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

Is this summary helpful??

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. If all looks good, then merge gh-pages into master and push to master Note: Debating on the utility of master branch - let's chat about it

Writing Posts or Pages

Pages vs Posts

A Post is any blog post on the site. On the other hand, a Page is any of other pages on the site (ex Contact, main Blog page, News, Archive pages, etc).

Jekyll lets you write posts in either Markdown or HTML. You will probably find it easier to write posts 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.

Drafting Posts or Pages

Unfinished pages or posts go in the collections/_drafts directory, so that Jekyll doesn't render them to the live site. You can preview draft page/post by adding the --drafts flag to the bundle exec jekyll serve command in your terminal (see Building & Serving the Site).

Posts Metadata

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

---
layout: post
title: My Cool Blog Post
date: 2012-03-07 13:59:23 -05:00
timezone: America/New_York
categories:
- PGP
- Tapestry
author: Author Name
permalink: "/2012/03/07/my-cool-blog-post/"
---

Some additional notes about the date and timezone fields:

Date

  • The format for the date field is YYYY-MM-DD HH:MM:SS.MS -TZ Offset, i.e. Year, Month, Day, Hours, Minutes, Seconds, Timezone Offset.
  • The Timezone Offset is optional, and reflects the region where you authored the post. This information is useful to RSS Readers and similar technologies. You can alternately include a timezone field (see below).

Example: New York would either be -05:00 for (Standard Time) or -4:00 for (Daylight Savings Time). For a full list of offsets, see Wikipedia - List of UTC Time Offsets.

While it's always better to be explicit, Jekyll will automatically infer the date from the title of your post, if you've left it out for some reason.

Timezone

The timezone can be indicated either by filling out the timezone field, or by including a timezone offset value in the date field (see below). This information would be useful to RSS readers or similar technologies. Time Zones should be listed in TZ Database format, and list can be found at Wikipedia - List of tz database time zones.

Pages 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.

Publishing Posts or Pages

Posts

Once you're done writing the post, move it to the collections/_posts folder. Note: Finished Posts must be named in the following format: 2019-09-23-your-really-awesome-post-name.md (or .html for HTML files).

Then follow the instructions in the Updating the Repo section of this doc.

Pages

If you've written a new page (instead of a blog post), move it to the root directory of the repo (you will see other files like blog.md, category.md, index.md, etc in this directory). Then proceed to the Updating the Repo section of this doc. If you need help finding the root directory, see the Files & Directories Guide.

Author Pages

Once you've finished writing your post and moved it into collections/_posts, please create an author page for yourself (if you don't already have one).

  1. In the collections/_authors/ folder, create a file named firstname_lastname.md.
  2. Include the following information:
---
name: First Last
gravatar_name: first_last
email: your@email.com
---

Regenerating the Post Archives

Note: This section is primarily intended for site admins (or other particularly tech-savvy individuals):

Once a post has been moved to collections/_posts, the yearly, monthly, and daily archive pages must be regenerated. This is done by navigating to the top (aka root) directory and running ruby _plugins/curii_archives_generator.rb. If you run into any errors, please run git checkout 2012 2013 2014 2015 2016 2019 (this will undo the incorrect changes to the archive pages).

If you were unable to successfully regenerate the archive pages, or if you added your post directly on GitHub (instead of the command line), please note this in your commit message by writing "Archives not regenerated" or "Archives error" or similar.

Updating the Repo

Once you're totally done with all your article or page writing, 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 Posts or Pages on Github

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

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 posts 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 post 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 post 'post_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-post. 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/_posts/post_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 Post Name and Author page, Add Page Name, Fix xyz on Page/Post 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.

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 Posts Or Pages On Github) section.

Push Your Changes to The Staging Repo

Type git push staging staging:gh-pages to push to the staging site. If you set up your branches and tracking correctly (or you ran the install script), then you can simply type git push

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

Clone this wiki locally