New Post Workflow

tutorials
website
Author

Michael McCarthy

Published

July 21, 2022

What you’ll learn

This document will guide you through the process of making new posts on our website. Here the term post refers to any page on the website that is collected under a listing page. For example, this document is a post that is collected under the documents listing page. The listing pages for this website include:

  • documents
  • events
  • news

You can make new posts under any of these listing pages following the workflow described in this document.

Note

You can also follow the general workflow described in this document to make other changes to the website.

How the website works

The OSSSG website is built using Quarto, and the source files for the website are managed on GitHub. The GitHub repository for the website is located at https://github.com/Open-Science-Student-Support-Group/osssg-website.

If you navigate to the GitHub repository you can view the source files for the website. The source files for the website fall into two broad categories:

  • Input files
  • Output files

Input files provide the scaffolding for the website, containing things such as settings for pages, written content, image files, and so forth. Output files contain the content that we publish to the web. This content is rendered by Quarto from the website’s input input files, then written to the _site directory. The _site directory contains the output files for the website (indeed, it is the website!); everything else can be thought of as an input file.

We publish the content in the _site directory to the web using Netlify, which is integrated with the website’s GitHub repository. Whenever a new commit is made on the main branch of the GitHub repository, Netlify will publish the content in the _site directory to the web.

Thus, the basic new post workflow involves:

  1. Creating an input file for the new post
  2. Rendering the site to update the _site directory to include the new post
  3. Committing the input file and _site directory to the main branch of the GitHub repository to publish the new post to the web

The remainder of this document guides you through this process.

Prerequisites

Set up Quarto

For creating and rendering new posts you will need to:

  • Install Quarto
  • Install an editor to use with Quarto

There are several editors you can use with Quarto. We recommend one of the following.

Install RStudio

Optionally: Read the Hello, Quarto RStudio tutorial. Note that if you want to run this tutorial yourself you will need to install R and the R packages used in the tutorial. However, you do not need to install R to work on our website.

Install:

Optionally: Read the Hello, Quarto VS Code tutorial. Note that if you want to run this tutorial yourself you will need to install the Python packages used in the tutorial. However, you do not need to install Python to work on our website.

Set up GitHub

For committing files to the website’s GitHub repository you will need:

There are many ways to connect your local computer to GitHub. We recommend one of the following.

Install GitHub Desktop

Note

We recommend this option if you’ve never used Git or GitHub before.

Set up RStudio’s built-in Git support

Note

We recommend this option if you already use Git, GitHub, and RStudio for other work. It’s especially nice when used in tandem with the usethis R package and its GitHub helpers and Pull Request helpers.

Set up VS Code’s built-in Git support

Note

We recommend this option if you already use Git, GitHub, and VS Code for other work.

If you’re considering this, you don’t need our help. 😎

Clone the website repository

After you’ve Set up Quarto and GitHub you can clone the website’s GitHub repository to your computer. If you have write privileges for the repository then you can clone the site directly; if you don’t then you will have to fork the repository and then clone your forked GitHub repository to your computer.

The steps to do this are a little different depending on the method you chose to connect your local computer to GitHub in the previous section. Make sure you note where you clone the website respository to on your computer so you can find it later!

Follow the cloning and forking instructions. The URL for our website’s repository is:

https://github.com/Open-Science-Student-Support-Group/osssg-website

If you do not have write privileges for the repository, first fork it on GitHub, then copy the URL of your fork and complete the steps below. If you do have write privileges, then copy the URL for our website’s repository and complete the steps below.

https://github.com/Open-Science-Student-Support-Group/osssg-website
  1. Open RStudio
  2. Create a New Project (from the Project of File menu)
  3. Choose to create a new project from Version Control
  4. Choose Git
  5. Provide the (forked) repository URL then click Create Project

Follow the pull request helpers instructions.

If you do not have write privileges for the repository, first fork it on GitHub, then copy the URL of your fork and follow the setting up a repository instructions. If you do have write privileges, then copy the URL for our website’s repository and follow the setting up a repository instructions.

https://github.com/Open-Science-Student-Support-Group/osssg-website

Starting up

Opening the project

With the prerequisites complete, you are ready to work on the website. The method to open the project depends on the editor you chose.

Double-click the osssg-website.Rproj file located in the root directory of the project. This will start an RStudio session for the project.

Open VS Code, then open the project’s folder inside VS Code, following the instructions here. This will start a VS Code workspace for the project.

Previewing the site

After opening the site you can open a live-reloading development server on your computer to preview the website while you work on it. Start the server by running the following in the terminal of RStudio or VS Code:

quarto preview

The development server will automatically re-render input files whenever they change. For more details see the Quarto website workflow documentation, and the sections on previewing with RStudio and VS Code.

The workflow

There are five steps to the new post workflow. The sections below will take you through each step.

1. Create a new GitHub branch

First you’ll want to create a new branch that you can work on your changes in.

Follow the creating a branch instructions.

Go to the (forked) website repository in your browser and create a new branch. Give the branch an informative name such as post_new-post-workflow.

Now do the following in RStudio:

  1. Go to the Git tab
  2. Click the Pull button in the Git tab
  3. In the upper right corner of the Git tab, click main, then switch to the branch you created

Follow the pull request helpers instructions.

See the branches and tags section for instructions on creating a new branch.

2. Create a new post

The _templates directory at the root of the project contains templates you can use to create a new post. Currently there are two templates:

The event post template is named 1999-01-24_event-post. This name will be used for the post in its URL on the site.

Modifying the template for new posts:

  1. Copy the 1999-01-24_event-post directory into the /events/posts/ directory
  2. Rename the 1999-01-24_event-post directory with the appropriate post date and event name
  3. Open the 1999-01-24_event-post/index.md file, edit and modify as needed
Warning

When renaming the post’s directory, follow the formatting used in the template (i.e., data_post-name). This keeps the posts organized and easy to parse. Do not include spaces anywhere in the name, only underscores (which should separate the date and post name) and hyphens (which take the place of spaces) are allowed.

The generic post template is named 2000-11-18_generic-post. This name will be used for the post in its URL on the site.

Modifying the template for new posts:

  1. Copy the 2000-11-18_generic-post directory into the /posts/ directory for the listing page you want to make a post in (e.g., news or documents)
  2. Rename the 1999-01-24_event-post directory with the appropriate post date and post name
  3. Open the 2000-11-18_generic-post/index.md file, edit and modify as needed
Warning

When renaming the post’s directory, follow the formatting used in the template (i.e., data_post-name). This keeps the posts organized and easy to parse. Do not include spaces anywhere in the name, only underscores (which should separate the date and post name) and hyphens (which take the place of spaces) are allowed.

3. Author your new post

Once you have copied the template for the new post to the listing page you want you can start editing the input file for the post. This is the index.md file located inside the directory for the post. Do not rename this file.

Please see the Markdown basics page under the Authoring section in the Quarto Guide for details on writing in Markdown, and the Websites section under the guide for website-specific concerns.

If you want to add icons or emojis to your post, see:

Note

If you are adding files to your post, such as images, they should be placed inside the post directory. This keeps the website organized, and allows you to link to the image using only its file name.

Try to reduce the size of the files if you can (e.g., by using image compression/optimization). Large files cause pages to load slower.

4. Commit and push your changes

When you are happy with your new post, run the following command in the RStudio or VS Code terminal:

quarto render

This will render all the output files for the site, including your new post. Now you’re ready to commit these changes to your branch. You’ll want to commit the following changes at minimum:

  • The input file for your new post
  • Any additional files your new post relies on (e.g., images)
  • Everything in the _site directory

For your commit message, choose something informative such as “Add ‘new post workflow’ post under documents”, replacing certain parts here with details relevant to your own post.

See the reviewing and committing changes to your project guide for instructions.

In the Git pane:

  1. Check all the files you want to commit
  2. Click the Commit button to open the commit pane
  3. Write your commit message
  4. Click the Commit button in the commit pane
  5. Click the Push button
Note

In the commit pane:

  • A yellow box indicates a file that hasn’t been committed before
  • A blue box indicates a file that is being modified
  • A red box indicates a file that is being deleted
  • A purple box indicates a file that had been relocated or renamed

In the Git pane:

  1. Check all the files you want to commit
  2. Click the Commit button to open the commit pane
  3. Write your commit message
  4. Click the Commit button in the commit pane
  5. Follow the submit pull request instructions
Note

In the commit pane:

  • A yellow box indicates a file that hasn’t been committed before
  • A blue box indicates a file that is being modified
  • A red box indicates a file that is being deleted
  • A purple box indicates a file that had been relocated or renamed

Follow the commit instructions, then Push your changes after committing them.

5. Submit a Pull Request

Once you have committed your changes to your new post branch, you can create a pull request to add these changes to the main branch of our website’s GitHub repository.

After you create the pull request, Netlify will create a Deploy Preview that you and your reviewer can use to preview your changes to the site before publishing them to production.

Follow the creating a pull request instructions.

Follow the creating a pull request instructions.

Follow the pull request helpers instructions

Follow the creating pull requests instructions

Cleaning up

If you forked our GitHub repository to make a new post, after your Pull Request is merged into the main branch of our GitHub repository you will want to clean up your fork. You have two options here:

  • Delete your forked repository
  • Delete the branch in your forked repository

The first option is better if you don’t plan to post again on our site. The second option is better if you do plan to post again on our new site since it means less work for your next post.

Your next post

If you deleted your forked repository, then simply repeat the steps in this guide all over again starting from the Clone the website repository section.

If you kept your forked repository and just deleted the branch you made in it, first Fetch the upstream changes from the main branch of our website’s repository, Pull those changes to your computer using GitHub Desktop or RStudio or VS Code’s built-in Git tools, then repeat the steps in this guide starting from the workflow section.

Resources