Create a new blog post

Tutorial

Tutorial how to create a new post on a quarto blog

Author

João Silva

Published

October 25, 2023

New feature!

Check a new feature here where you can see extra yaml configs we integrated to your posts.

Production environment available!

The public blog available even outside EPFL network and without gaspar is availbale here. Include prod: true in your yaml config and validators will review it before adding it to the production environment. (make sure you dont post confidential data)

Create a new blog post

This document presents how to publish blog post in the ipese research blog

Two versions are available:

Development version: It is accessible only when logged in EPFL’s authentication server (tequila) with your gaspar account via the website

Production version: Accessible to everyone under this url The repository of this project is in gitlab.

You can add posts to this Quarto blog in any of the menus on the navbar. Blog articles are written in Quarto, which is similar to Markdown. You can also run R or Python code chunks in your posts, import .bib files, and use many other features.

Setup development environment

1. Installation

Make sure you have R installed

    R --version

if not, install it with:

    brew install R

Make sure you have quarto installed

    quarto --v

if not, install it via the quarto website

Install markdown packages for R

    RScript -e "install.packages( c('rmarkdown','reticulate'))"

terra package is installed automatically but is sometimes tricky to install, you can try with:

    RScript -e "install.packages('terra')"`

if there is an error you can try the following commands in order:

    brew install pkg-config && brew install gdal
    RScript -e "install.packages(c("raster", "Rcpp"))"
    RScript -e "remotes::install_github("rspatial/terra")"

Make sure your R can find your python installation

    RScript -e "library(reticulate); reticulate::py_config()"

You can easily correct this with:

    RScript -e "library(reticulate); reticulate::install_python()"

install the python package bs4, requests and psutil that is used in a post-render script

    python -m pip install bs4 requests psutil`

2. Install quarto extension and connect with zotero API

If not yet installed, install VS Code as this is the tool we are going to use for most projects
In VS Code install the quarto extension
Go to zotero.org and log in your account
In your account go to settings and then Feeds/API
Here you can create a new API key with a name of your choice
Copy the new API and save it because you won’t be able to access it again once you leave the page
Access your settings (⌘ + ,) and look for zotero in the search bar
In the Zotero: Library choose web and you’ll be prompted to add your API key
In Group Libraries click on Add Item and write IPESE and ok
You can now edit in visual mode by clicking the 3 dots on the top right or ⌘⇧P and enter Visual Mode
- By clicking in insert and Citation, you can see a list of citations available
- When adding a citation it will automatically add the information on a bib file, the reference to you yaml header and the citation where your text cursor is located

3. Other extensions you might add

Live Share by Microsoft allows you to create a link and allow collaborative editing with others with whom you share it with.
- Other users can open the link and use wbe version or open in VSCode, connect their account or simply choose a user name.
- After that, you (the person who created the link) need to accept the new user as an Edit or a read-only user.
Draw.io integration by Henning Dieterichs to edit drawio files (use drawio.svg extension so that you can use the svg integration library developed by ipese)
- Simply create a new .drawio file or open an existing one and it will open an interface that allows you to edit the diagram.
Edit csv by janisdd to edit csv files
- Create or open a .csv and click on “Edit csv” on the top right.
Excel Viewer by GrapeCity to edit xlsx files
- Open an .xlsx and you’ll be able to edit your content in a simplified graphical interface
vscode-pdf by tomoki1207 to visualise pdf in vs code.
- This allows you to view pdf files in VSCode, which is impossible otherwise.
vscode-pydata-viewer by Percy to view pickl files
- This uses your pandas installation to display data and it needs to by version < 2.0
GPT by Silas Nevstad to use GPT in vs code (need for an API key)

Before writing

Before you start writing, you need to create your folder and edit some settings and options.

Create new folder

To create a new blog post, simply copy the _template folder and paste it into the folder for the submenu where you want your post to be:

- Home	-> posts
- Urban Systems	-> urban_systems
- Process Design	-> process_design
- Energy Systems	-> energy_systems
- IT Tutorials	-> it_tutorials

You’ll need to rename the folder with a name that doesn’t start with _, doesn’t contain " or ' and avoids white spaces.

To have a naming convention in place, you should name the folder with a name like this: yyyy-mm-dd-title-of-your-post.

Define the list of authors

This blog outouts files in docx and pdf so it’s imperative that the authors are mentioned in all documents as they might be shared outside of this blog.

Edit the configurations

Next, edit the YAML header of your index.qmd file to add a title, author name, date, description, and image. The other elements in the header, such as comments, toc, and format, can be left as is.

The other elements are:
- comments: in our sample, are turned on with hypothesis
- toc: or table of contents that is used to display the titles on the side of the article (here on the left and with 3 level of titles expanded)
- format: other info for the rendering process, code-copy: true will display the code chunks with echo=T with a button to copy to clipboard

Add categories

Under categories: add the ones related to your post. These are the categories already used in the blog :

Blog
CO2 emissions
Tutorial

You should use these categories as much as possible instead of creating new ones. Although, this list is updated every time you render the website.

Unlisted posts and includes

Every qmd in your folder is rendered as a post by default. To create posts that are not listed you can add hidden:true or draft:truein the yaml of the header. You can still reference this post by creating a link with its path and replacing .qmdby .html The difference between hidden and draft is that hidden is hidden by the parameters of the listing and draft is hidden by the main quarto framework.

You can also make one post with multiple .qmd files. For this you can either use the hidden:truein the secondary file or start it’s name with _ you can then include your file like this:

{{< include _partialfile.qmd >}}

Although if you name a file starting withh _, and don’t reference it in an include, it won’t be rendered.

hidden:true works in all cases for this blog.

Extra yaml properties

Thanks to the scripts added in this project, some additional properties are available in the yaml for each post:

Add a Mattermost link to a group that concerns your post:

    chat: https://ipese-mattermost.epfl.ch/ipese/channels/it

Include your post in the production environment (this will deploy it to a test environment and send a message to a Mattermost group for validation, it will be transferred to a production environment when validated in that private group chat):
- also available in member pages

    prod: true

Include bibdatamangement in your post. This will automatically activate a python virtual environment with all the packages installed and use the files you mention in these properties. This will be activated if you have a bibliography and either add a default-values CSV or have bibdata: true. (check bibdatamanagement documentation for more info)
- A script will automatically include a quarto include in the post that will activate the needed libraries thus changing some files in the repository

    bibliography: '***.bib'
    bibdata: true
    params:
        default_values: '***.csv'

Initiate a venv in the mentioned path. Leave the default path to use the same venv folder as other posts or change the path to “./venv” to have your personal venv folder for testing locally if needed.

    venv: ../../venv

Include rosmose in your post. This will create the virtual environment and run the rosmose-setup.R script.

    rosmose: true

In members pages, you can add a path to a folder from the zotero IPESE group. This will create a references.bib file with all the citations in that folder and include it in your page.

    zotero: "@members/**/**"

Available scripts

For your information, these scripts are also available to add in the _quarto.yml post-render nad pre-render section that will add functionalities to the whole blog:

To retrieve all the categories used in the blog and add the list in every div of class categories-list

  post-render:
    - ./resources/scripts/getCategories.py

To add the action buttons such as the download as pdf or word, link to mattermost chat or edit button:

  pre-render:
    - ./resources/scripts/add_actionButtons.py

To add the chatbot to the whole website that is connected with the ipeseai bot:

  post-render:
    - ./resources/scripts/add_chatbot.py

To clean the repository after a successful build eraseing .tex files, .bst files and code added by the previously executed scripts:

  post-render:
    - ./resources/scripts/clean_repo.py

To deploy the whole website in a personalised manner for our group, this script deploys each type (html, pdf, docx) seperatly and disables posts that don’t work.

  post-render:
    - ./resources/scripts/deploy.py

Write in Markdown

You can add titles by starting the line with # like this:

# Main title
## Secondary title
### Tertiary title

You can then add multiple types of data like

Text
Link to a website
- [link to a website](https://www.google.com)
- link to a website
Link to another qmd file
- [another file of this post](otherfile.html)
- another file of this post
Bold text
- **bold**
- bold
Italic text
- *bold*
- bold
Bold and italic text
- ***bold***
- bold
Unordered list:
- Main point
  - secondary point
Ordered list:
1. Main point
  1. secondary point
Tables are also possible:

Aligned to the left Centered col Align to right

Content Content Content

Content Content Content

Aligned to the left	Centered col	Align to right
Content	Content	Content
Content	Content	Content

What about code chunks?

You can also run or display code chunks like this:

    if(!require('reticulate'))
        install.packages("reticulate")

Loading required package: reticulate

Options available for customizing output include:

Option	Description
eval	Evaluate the code chunk (if false, just echos the code into the output).
echo	Include the source code in output
output	Include the results of executing the code in the output (true, false, or asis to indicate that the output is raw markdown and should not have any of Quarto’s standard enclosing markdown).
warning	Include warnings in the output.
error	Include errors in the output (note that this implies that errors executing code will not halt processing of the document).
include	Catch all for preventing any output (code or results) from being included (e.g. include: false suppresses all output from the code block).

Also, your chunks with echo=T, if the code-copy is true in this file, will have a copy to clipboard button.

Deploy the changes

The deployment process aims to construct the entire blog recursively, persisting until completion without encountering errors. If a blog post is identified with an error, it will be excluded from the final build output. This means that if an error is identified in your post, it won’t appear in the deployed website.

The changes can be deployed to the online blog here To achieve this you need to push a commit to gitlab with a tag, which can be achieved with a Git client like Fork or GitAhead, in the terminal or with the Gitlab IDE. To have a tutorial that works in all installations, here is a tutorials to do this with VS Code which is the recommended software to work on this project:

Add a post to the production website

To publish a post on the production website, include prod: true in the YAML header of your post. This version will then be published in the test environment here and it will need to be accepted via the mattermost channel created for this (only some members have access to this channel). When accepted, it will be available here.

On the production side, the Edit and Chat buttons are disabled, emphasizing the need to deploy only the final version of your post to this website. Additionally, ensure that all data can be shared, considering that the production website is accessible to everyone, including users without VPN access and those without access to Tequila.

VSCode

In the sidebar on the left, go to the git menu:
Git pull to make sure you have the latest version of the blog
Here you can find a list of files you have changed or added. Click on the plus icon next to changes to stage all files or add one by one.
Write a short message that represents the changes you have made.
Click on the arrow next to Commit and choose “Commit & Push”
To create a tag and deploy to the test environment, click on the git graph to view the commit and branch history. Here you can right click the commit you want to create a tag and select Add tag.... Add a name (unique) to your tag and select the checkbox Push to remote before clicking on Add tag