How to add post entries

Instructions on how to add post entries to Quarto-based websites.

Compared to blog/website generators of the past and of many current ones, adding a post to this Quarto website is relatively straight-forward. For now, I’ll focus on adding a post to the Community section of the website, though these principles apply to any post/collection we use throughout this site (e.g. the Community Contributing Guide Entries is a collection of post entries).

There are two ways to add a post:

1. Cloning the community GitHub repository to your computer
2. Creating and writing directly inside the GitHub repository

If you contribute often to the project, going the first route is highly recommended. But if its only a quick thing or you are an infrequent contributor, then the second might make more sense for you.

Regardless, in both routes the steps are:

1. Create a new file inside posts/ with a short name the describes the post. For instance, this post’s file name is adding-posts.qmd.

2. Open up the new file and add the below metadata to the top of the file. This is called the YAML header.

   ---
   title: ""
   description: ""
   author: ""
   date: ""
   categories:
     - ""
   ---

3. Edit the YAML metadata but putting the title of your post inside the brackets of title: "". Do the same for description (a one or two sentence overview of your post content), author (your full name), and date (in the form of YYYY-MM-DD like 2022-10-31). You can add multiple categories to the post by adding a new line starting with - below the previous category. You can write whatever topic word or phrase you want for this. See the YAML metadata of this post for an example of what it should look like.

4. Then, you can start writing the content of the post below the --- under the metadata. You need to write posts in Markdown (see this guide for how to write Markdown).

5. After you are done writing, the final step is to get the post into the community Git history. This step depends on if you cloned the repository or if you are writing directly in GitHub.

   • In GitHub, it is relatively simple. At the bottom of the page is a section called “Commit changes”, where there is a text box to write a “commit message” and a green button to “commit changes”. Write a short message about what you are adding and optionally why. Below that message is a choice to create a new branch and start a pull request. You will probably be forced to select that option.

   • If cloned, you will need to create a new branch and add and commit the new file with Git. Depending on what IDE or application you use will change how you do these actions. Since the command line is a common way of working with Git, I’ll show the commands to run for that:

     # Create and move to a new branch. 
     # Call the branch any name you want, 
     # I'll use the `adding-new-post`.
     git checkout -b adding-new-post
     # Replace `NEW_FILE` with the actual name of the file
     git add NEW_FILE 
     # Add a short message about what you are committing
     git commit -m "New post about BRIEF_DESCRIPTION"
     # Push the changes up to GitHub
     git push origin adding-new-post
     # Switch to the main branch
     git checkout main

     After pushing up the GitHub, you will need to go to the repository and create a new Pull Request from your newly pushed branch.

   • No matter if you want to add a file directly on GitHub or via the command line, you can find more guidance in the GitHub Docs.

6. You are all done! That’s it 😄

More details about creating posts can be found on the Quarto documentations.