All you need to create a blog post in the Open Science Community Saudi Arabia using Quarto?

This is a step-by-step guide on how to create your first a blog post without any coding.
blog
quarto
outreachy
Author

Richie Moluno, Goodnews Sandy

Published

December 8, 2022

What is Quarto?

Quarto is a new open source project that aims to make it easier for people to create and publish blog posts. It is a static site generator that uses the Markdown syntax to create blog posts. Quarto is written in the R programming language and is available for download on GitHub.

Get started

Prerequisites

To get started with contributing with Quarto, you will need;

  • A GitHub account.
  • A basic understanding of Markdown is recommended but not necessary. Here is a guide

Install Quarto

To install quarto on your computer, you can download the latest version of R from the R Project website.

To Download the latest version of quarto visit the Quarto website.

Setup Local environment

To start making contributions to the OSCSA blog, you will need to add the OSCSA blog repository to your personal Github account. This will allow you to make changes to the blog without affecting the live version of the blog.

Step 1 - Fork the repository

To get started, fork the OSCSA blog repository from GitHub.

Create new fork

Step 2 - Create a new branch

Next create a new branch for your blog post using the following steps, the branch should be created on your forked repository.

  • To create the new branch, navigate to your forked repository.
  • Under the repository name, click on the drop down menu and select the View all branches option.

View all branches

  • Click the New branch button.

Create new branch

  • Enter the name of your new branch and click the Create branch button.

Create new branch

Create a new blog post

To create a blog post using Quarto, you would need to first create a Markdown file using the Quarto syntax. Markdown is a simple markup language that is often used to format text on the web. The Quarto syntax extends the basic Markdown syntax with additional features and functionality, such as the ability to add columns, tables, and other advanced formatting options.

For this tutorial, we won’t be building a blog from scratch. Instead, we will be adding new posts to the OSCSA blog using Quarto.

Step 1 - Create a new folder

  • Switch to the branch that you created in the previous step.

  • Navigate to the posts folder and create a new folder with the name of your blog post. For example, if you are writing a blog post about how to add a blog post using Quarto, you can name your folder how-to-add-a-blog-post-using-quarto.

  • Type the name of the folder followed by a forward slash /. This would create a subfolder in the posts folder. The folder name should be in lowercase and should not contain any spaces. Instead, use hyphens to separate words.
Step 2 - Create a new file

You’ll need a new index.qmd file. This is where you will write your blog post using the Quarto syntax.

  • Add the name of the file that you want to create. For example, if you want to create a file named index.qmd, type index.qmd Create new file

  • Press the Commit new file button to create the new folder and file. Commit new file

Step 3 - Add Metadata

The index.qmd file should contain the following metadata:

---
title: "My first blog post using Quarto"
author: "Richie Moluno, Goodnews Sandygudie"
date: "2022-12-08"
categories: "blog"
description: "This is my first blog post for the OSCSA blog using Quarto."
licence: "CC BY"
type: "post"
image: "./quarto.png"
citation: 
    url: https://oscsa.netlify.app/posts/my-first-blog-post/
---

The yaml block is a set of metadata that is used to describe the blog post. It is written in YAML format and is enclosed in three dashes. The yaml block contains the following fields.

  • title: The title of your blog post.
  • author: The name of the author of the blog post.
  • date: The date the blog post was published.
  • categories: The categories that the blog post belongs to.
  • description: A short description of the blog post.
  • licence: The licence that the blog post is published under.
  • type: The type of blog post. This can be either a post or a page.
  • image: The image that will be used as the featured image for the blog post.
  • citation: The citation for the blog post.

Step 4 - Write your blog post

After the front matter, you can start writing your blog post using the Quarto syntax. The Quarto syntax is a simple markup language that is often used to format text on the web. It extends the basic Markdown syntax with additional features and functionality, such as the ability to add columns, tables, and other advanced formatting options.

For example, you can use # characters to create headings, - or * characters to create bullet points, and > characters to create block quotes.

For this tutorial we’ll be using dummy text to write our blog post. You can replace the dummy text with your own content.

# My first blog post using Quarto
Magna ad anim nulla reprehenderit ea dolor ullamco Lorem ad consequat enim. Et officia qui sit tempor voluptate aliqua enim deserunt laboris enim nulla ullamco. Non eiusmod esse esse amet enim dolore sint culpa. Esse anim duis elit velit aliqua et. Proident incididunt magna voluptate laboris laborum eiusmod deserunt dolore mollit fugiat quis cillum aliquip. Nulla quis id aute duis aliquip officia in enim duis laborum aute duis. Aliqua sunt fugiat nostrud officia esse occaecat commodo est.

## What is Quarto?
![](./quarto.png){fig-align="center" width="100%" fig-alt="quarto"}   <!-- Image file -->

Mollit eiusmod culpa in ad esse nulla est do consectetur. Eiusmod et Lorem sint veniam nisi minim ad velit sit culpa. Occaecat culpa sint cupidatat minim elit commodo labore mollit est ipsum. Anim officia est tempor esse voluptate occaecat nulla velit elit officia elit consectetur enim. Aliqua est reprehenderit culpa labore magna ut deserunt. Proident ex ad quis exercitation dolore minim cupidatat ad pariatur. Est minim irure enim non incididunt velit laborum est adipisicing enim eiusmod quis.

Note: If you dont know how to write a blog post using the Quarto syntax, you can check out the Quarto documentation for more information.

If you don’t want the blog post to be published immediately, you can add the following field to the yaml block:

draft: true

Step 5 - Add images

To add images to your blog post, add the image file to the same folder as the index.qmd. You can then reference the image in your blog post using the following syntax:

![](./<image-name>.<image-extension>)

Step 6 - Commit your changes

Once you have finished writing your blog post, you can save the file and commit your changes to your forked repository.

Step 7 - Create a pull request
  • Next, create a pull request to merge your changes to the main branch. You can do this by navigating to the GitHub repository and clicking on the New pull request button.

New pull request

  • The branch for the base repository should be set to main and the branch for the head repository should be set to the branch that you created in the previous step. Click the Create pull request button to create a new pull request.

Create pull request

  • Add a title and description for your pull request. The title of your pull request should be a short description of the changes that you made. it should follow the format [blog]: Title of your blog

  • Automatically, the PR template will be added to the description of your pull request. You can add more information about your pull request in the description.

  • Click the Create pull request button to create a new pull request.

Create pull request

Step 8 - Merge your changes

Once you have created a pull request, you can wait for your changes to be reviewed and merged to the main branch.

Preview your blog post

If you followed the steps carefully, your index.qmd file should look like this:

---
title: "My first blog post using Quarto"
author: "Richie Moluno, Goodnews Sandy"
date: "2022-12-08"
categories: "blog"
description: "This is my first blog post for the OSCSA blog using Quarto."
licence: "CC BY"
type: "post"
image: "./quarto.png"
citation: 
    url: https://oscsa.netlify.app/posts/my-first-blog-post/
---

# My first blog post using Quarto
Magna ad anim nulla reprehenderit ea dolor ullamco Lorem ad consequat enim. Et officia qui sit tempor voluptate aliqua enim deserunt laboris enim nulla ullamco. Non eiusmod esse esse amet enim dolore sint culpa. Esse anim duis elit velit aliqua et. Proident incididunt magna voluptate laboris laborum eiusmod deserunt dolore mollit fugiat quis cillum aliquip. Nulla quis id aute duis aliquip officia in enim duis laborum aute duis. Aliqua sunt fugiat nostrud officia esse occaecat commodo est.

## What is Quarto?
![](./quarto.png){fig-align="center" width="100%"}   <!-- Image file -->

Mollit eiusmod culpa in ad esse nulla est do consectetur. Eiusmod et Lorem sint veniam nisi minim ad velit sit culpa. Occaecat culpa sint cupidatat minim elit commodo labore mollit est ipsum. Anim officia est tempor esse voluptate occaecat nulla velit elit officia elit consectetur enim. Aliqua est reprehenderit culpa labore magna ut deserunt. Proident ex ad quis exercitation dolore minim cupidatat ad pariatur. Est minim irure enim non incididunt velit laborum est adipisicing enim eiusmod quis.

To see a preview of your blog post, you can visit the netlify preview link that was generated when you created the pull request.

Netlify preview link

Conclusion

In this tutorial, we learned how to use Quarto to create a blog post in Github. We started by forking the original OSCSA blog respository to our Github account. We created a folder and added a file called index.qmd and use the Quarto syntax to add content for our blog. Finally, we commited our changes and submitted a pull request. Our blog post can be viewed using the netlify preview link.

References

Citation

BibTeX citation:
@online{moluno,goodnewssandy2022,
  author = {Richie Moluno, Goodnews Sandy},
  title = {All You Need to Create a Blog Post in the {Open} {Science}
    {Community} {Saudi} {Arabia} Using {Quarto?}},
  date = {2022-12-08},
  url = {https://oscsa.netlify.app/posts/how-to-add-a-blog-post/},
  langid = {en}
}
For attribution, please cite this work as:
Richie Moluno, Goodnews Sandy. 2022. “All You Need to Create a Blog Post in the Open Science Community Saudi Arabia Using Quarto?” December 8, 2022. https://oscsa.netlify.app/posts/how-to-add-a-blog-post/.