How to use the MCT Blog ‐ Creating a Blog Post

< Back to "How to use the MCT Blog"

Step 0 - Cloning the mct-master.github.io repository

This step is necessary only the the first time you use the blog, or when you use a different computer, or if you have previously deleted yout local copy of the repository.

1. Open GitHub Desktop, under Preferences -> Accounts click on Sign In and enter your GitHub.com credentials.

2. In GitHub Desktop, select File -> Clone Repository... and select MCT-master/mct-master.github.io from the GitHub.com tab (you should find it there if you completed correctly step 0.1 and the Prerequisites). In the same dialog window, select the Local Path (i.e. in which local folder you want to store the a copy of the repository).

   • Alternatively, you can enter the URL https://github.com/MCT-master/mct-master.github.io.git. Another method is to open the mct-master.github.io repository in the browser, click on the green button Code, and select Open with GitHub Desktop.
   • Cloning the repository it will take some time. If your computer displays hidden files and folders, you should never manually edit or move the hidden subfolder .git (this contains the history of the repository, and it may have a significant size).

3. In your local copy of the repository mct-master.github.io, copy the file the file pre-commit from the folder utils to the hidden folder .git/hooks. It is important that you copy the file and not move it (or cut/paste). The folder .git is hidden, if you do not know how to show/hide hidden files, check out this brief guide. Also, ensure that the file pre-commit is executable using the command (in the Mac-OSX/Linux Terminal or Window Power Shell) chmod +x pre-commit. This step installs a specific a “git hook”, which is a script called every time you create a commit. This script returns an error (on both git command line and Github Desktop app) if any file you try to commit:
   • Exceeds 300 KB in size (such files must be stored on the UiO Vortex blog folder)
   • Include whitespaces in the filename (create problems with URLs)

Step 1 - Adding a new post file

1. In GitHub Desktop, update your local repository by selecting the mct-master.github.io in the Current Repository top-left menu of GitHub Desktop and then click on the Fetch origin (or select Repository -> Pull).

   • It is a very good practice to update your local repository before you start working on it.

2. Open the repository in VS Code selecting File -> Open Folder... and select the folder mct-master.github.io in the dialog window (this should be in the Local Path you selected in step 0.2).

   • Alternatively from GitHub Desktop, after selecting the mct-master.github.io in the top-left menu you can click on the Open in Visual Studio Code button (or select Repository -> Open in Visual Studio Code). This requires you to configure VS Code as your external editor under GitHub Desktop Preferences (under Integrations).

3. In the Explorer panel of VS Code, right click on the folder _post_drafts and select New File (alternatively left click on folder and select File -> New File). The file must be named YYYY-MM-DD-short-version-of-title.md where YYYY is the year of the post, MM is the month of the post, and DD the day of the post, .md represents the Markdown file extension. MM and DD should always be two digits (i.e. do not use 2020-1-1-title.md for the first of January 2020, but 2020-01-01-title.md). The short-version-of-title must not contain spaces (use hyphens), because this name determines the URL of your blog post, i.e. https://mct-master.github.io/category/YYYY/MM/DD/short-version-of-title.html (more on category later). Spaces or special characters are not allowed in the file name.

   • files with names not aligned with the format described above will not be saved in the repository and associated posts will not be visible in the blog.
   • VS Code is able to understand the content of a GitHub repository and in the Explorer panel files and folders are color coded accordingly:
     • Light gray - local copy identical to the repository
     • Dark gray - ignored, i.e. will not be considered when committing changes
     • Green - new, i.e. will be added to the repository when pushing the committed changes
     • Orange - modified, i.e. repository will be updated when pushing the committed changes
     • Mind that renaming a file is equivalent to delete a file (red but this is not shown in VS Code) and adding a new one (green). When deleting a file from an existing folder, the folder will show in orange (modified).

Step 2 - Including the frontmatter

The YYYY-MM-DD-short-version-of-title.md file you created in Step 1 is nothing more than a plain text file you can edit and save in Atom. The top part of the text file must include the frontmatter. The frontmatter includes important information related to your blog post. This is not visualized in the the Markdown preview, but these information are used when the associated webpage and list of blog post are automatically generated. In the frontmatter, you should include all the field as in the following template.

---
layout: post
title: "Title of the blog post"
date: YYYY-MM-DD HH:MM:SS Z
categories: category-name
author: Name1 Surname1, Name2 Surname2 
image: /assets/image/featured_image.jpg 
keywords: comma, separated, list, of, keywords
excerpt: "A short summary, typically copy-pasting the first paragraph of the blog post."
---

• layout: this must be set to post
• title: this field includes the post title and must be between double quotes (i.e. " ") and it can contain spaces. This title till be displayed on top of your post page and on the post list. The title can be longer and more articulated than the short version of the title you used to name your Markdown file.md. However, it recommended to avoid lengthy titles.
• date: this field indicates the date of the post and it should follow exactly this format YYYY-MM-DD HH:MM:SS Z (mind the single space between the three fields). Z represents the timezone with respect to the GMT. For instance if you are posting from Oslo, use +0200. Time and time zone can be omitted.
• categories: this field specifies the category to which the post belongs. The category will be displayed below the post title in pages including list of posts from different categories (such as the homepage). The category doesn't not show elsewhere, but it determines in which specific list the post is shown. Using more than one category is possible, they must be separated by space. However, this is not a common practice in the MCT Blog (the associated post will show up on both lists). The following is a list of categories allowed in the posts (mind that there is no spacing between words but an hyphen). In the blog there is a list of associated post for each category (available through the menu on the blog header).
  • applied-project
  • interactive-music
  • machine-learning
  • masters-thesis
  • motion-capture
  • networked-music
  • other
  • people
  • sonification
  • sound-programming
  • spatial-audio
• author: this field includes the list of author. For posts with a single author this field should be set to Firstname Lastname (i.e. there is a space in the between). For posts with multiple authors, the names should be comma separates, such as Firstname1 Lastname1, Firstname2 Lastname2, Firstname3 Lastname3. Do not use "&" or "and" to separate the last author in the list. It is very important that author names are consistent throughout the blog (i.e. never use abbreviations or nicknames) because posts are linked and listed to individual author pages. For more information on author naming conventions, check the Author's Page guide.
• image: this field is the relative path and file name to the featured image, which is shown only in the post list on the right side of the post excerpt. The featured can be one of the images included in the blog post, but it can also be something else, perhaps a more catchy image more representative of the overall contents. In order to look good in the post list, the featured image must be squared (i.e. identical width and height). We recommend images not exceeding 300x300 pixels. Featured images must be stored in the repository sub-folder /assets/image/ and should be named according to a specific convention, have specific extension, and size limit. Guidelines and details are included in the guide Embedding and Storage of Files which you should read next. Ensure that you do not use backslashes (i.e. \ ) in the file path, as the featured images will not show in the preview when sharing the post on social media.
• keywords: this field includes a list of comma separated keywords associated to the post. At the moment there is no functionality in the blog associated to keywords, but this may be added in the near future. A single keyword should not contain spaces, therefore use an hyphen for composite keywords, such as artificial-intelligence.
• excerpt: this field included the excerpt, which is a short paragraph that shows only in the list of posts, such as in the homepage. The excerpt must be between double quotes (i.e. " ") and it can contain spaces and punctuation. The excerpt should be a a short summary of your post, or you can copy the first paragraph of the post (perhaps truncated with ellipsis ...). The excerpt should have a length of approximately 20-30 words to look good in the pages including a list of posts. When previewing your blog post with Jekyll, ensure that the excerpt does not exceed the preview box in the blog homepage.

When you are done with the frontmatter, it is recommended that you save the file on your computer (at this stage there is no need to commit this change in thee repository, more on this later). Frequent errors in the frontmatter are related to the improper use of spaces, commas, quotes, slashes and hyphens. When compiling the frontmatter you should pay a particular attention to this. Just an extra comma or a missing space mat determine the improper visualization of your blog post, and figuring out why this is happening may take a lot of time.

For a better understanding of the frontmatter, you can explore the contents of Markdown files .md (perhaps the recent ones) in the repository folder _posts against the associated contents in the MCT Blog both as posts and in the entries in the post list. If you are searching for specific matching contents (text), on the blog you can use the Search page, and on VS Code you can use the Edit -> Find in Files functionality.

Step 3 - Developing and previewing the post

1. After the frontmatter, the file.md should include the actual contents of the blog post (text and multimedia) in Markdown writing format. This guide is only focused on the overall workflow to produce a blog post. This guide does not explain how to develop and organize the contents of the blog post,. More details on Markdown syntax are in the Prerequisites guide, while guidelines for embedding multimedia files are included in the guide Embedding and Storage of Files. In addition you can investigate the Markdown of existing blog posts to understand how certain contents are coded.

2. While developing the contents of the blog post you can use the the markdown preview functionality of VS Code (we recommend installing the enhanced preview extension) to have a preliminary look at how your post will look like once published. In VS code, you can open the preview pressing '⇧⌘V'. If you want to display the preview in the browser, save the file (i.e. not a live preview), right click on the preview window and select Open in Browser. Mind that this is a plain preview of the Markdown contents (it also renders the HTML needed to embed certain multimedia files). The previewer is not able to interpret the frontmatter, and it does not know anything about the styles used in the blog. Therefore the following will not be visible:

   • the header of the blog post, which includes title, author, and date
   • the footer of the blog, which includes contact information, social media links, and description
   • the text of the post appear all black instead of using the blog theme colors
   • the text will appear right aligned instead of justified
   • media files alignment and size may be inaccurate
   • there may be minor differences in how line break are handled (useful clarification on line break in Markdown are available here here)

3. When you think that you blog post if ready (likely after iterating a few times between steps 3.1 and 3.2) you can check out how it would look like when published in the blog. First of all, you need to move your file.md from the folder _posts_draft to the folder _posts. You can do this in the Explorer panel of VS Code just by dragging the file across the folders. Then open the command line terminal, and change directory (use the command cd) to your local copy of the blog repository. The name of the folder is mct-master.github.io and you should find it in the Local Path you specified in Step 0. Then enter the command bundle exec jekyll serve, and wait until you get the message Server running.... Then open your browser and enter the following address https://127.0.0.1:4000/ or https://localhost:4000/. This will open your local copy of the MCT blog statically generated by Jekyll, where you can check the how the preview of your blog post looks like in the post list (if it is a new post, likely it would be the first in the Latest list), the layout of the excerpt and of the featured image, the authors, if the post shows up in the right category, and how the contents in the blog post itself looks like. If you find anything wrong, you can modify the file.md and save it. Jekyll will automatically detect that a file has changed and in a few seconds it will regenerate the static blog. Reload the page in your browser and short while it will regenerate the associated pages does it look when accessing the actual post.

Step 4 - Publishing the post

1. Everything you did so far, until Step 3, exists only on your computer. When your post is ready and looks good, is time to publish it. Save and close all files you edited in VS Code.

2. Open GitHub Desktop and select the mct-master.github.io in the Current Repository top-left menu.

3. In the Changes tab on the left you will see a summary of the changes you have done. Remember that these are color coded, where green represents a new file, orange a modified file, and red a deleted file. If you are dealing with text files (such as the file.md associated with a blog post), by selecting the file in the Changes tab, the main window of GitHub Desktop will show you what changes has been done (white background unmodified, red background, deleted, green background added). Carefully review all files that appear in the Changes tab. These should be those that you have created, added, or modified when working on your blog post. If other files appear, which you may had inadvertently changed or created, you must uncheck them. New files (green) must not exceed 300 KB in size, and should not include whitespaces in the filename.

4. After reviewing the list of changes and selecting only what you want to update in the online blog repository, enter a meaningful name to your commit (in the field Summary) and optionally include a very brief description (these are useful in case we have to roll back the changes). Then clock on the blue button Commit to master. This create another entry in the history timeline of the repository (you can check that in the History tab), but this entry and the new/modified files still only exist on your computer. You will notice that not what the Fetch origin button has changed to Push origin. Click that button to push your changes in the repository and publish your blog post (or select Repository -> Push). It will take a short while (usually a few minutes) until the changes are visible in the MCT Blog, because Jekyll running on the GitHub server has to re-generate the static version of the blog. You may not see the changes due to local cashes, in this case try to clear your browser cache or access the bog using an incognito tab.

Step 5 - Editing a published post

1. In GitHub Desktop, update your local repository by selecting the mct-master.github.io in the Current Repository top-left menu of GitHub Dedktop and then click on the Fetch origin (or select Repository -> Pull).

2. In VC Code, expand the folder _posts in the Project panel, and open the file.md associated to the blog post you want to edit.

3. Implement the required changes and preview them as detailed in Step 3. The extent to which you want to check preview depends on how confident you are with the MCT blogging tools and the degree of the changes. If you have to fix a typo you may skip previewing the post. If changing something within the body text of the post, checking it out with VS Code markdown preview is usually sufficient. If you are changing anything in the frontmatter or if you are doing find adjustments to the layout or to embedded files, you have to double check the changes building the static blog with Jekyll.

4. After verifying the editing you made, you can commit and push the changes to the repository following the instructions in Step 4.

You should avoid to commit too many times or too often, as this, on the long term, will affect the sustainability of the blog repository (unnecessary grow in size) and it will make the process of rolling back specific changes more difficult. Consolidate all the changes you want to make and file you want to add in a single commit and then push it to the repository (the problem is not the frequency of pushing rather the the commits, as these create an new entry in the repository history). Ideally each new blog post should correspond to a single commit, you should not use the repository as a place to save your incomplete drafts, unless you are collaborating with others on the same blog post. This does not mean that if you find a small typo in your post you should not commit such a small change. However, you are recommended to proof read your posts, and to check as much as possible with the previewing tools before publishing new posts or committing edits to existing posts.

When something goes wrong

A person who makes few mistakes makes little progress. When something goes wrong (no matter how careful you are, it can be mathematically proven that this will happen) you should learn how to roll back time using the infrastructure behind the MCT Blog (i.e. Git repository). To start, a good reading is Oh Shit, Git!?!, which describes how Git can help you to fix mistakes in several scenarios. The page refers to the command line version of Git, but the same functionalities are available through the graphical interface of GitHub Desktop.

• Undo changes not yet committed with VS Code - If you have not yet committed your changes you can simply Undo your changes in VS Code, even after you saved the files (this will not work if you close Atom after saving the files, and then you open it again). In VS Code files containing changes not yet saved are marked with a white circle next to the file name in the top bar. As described in Step 1.3, VS Code is able to understand the content of a GitHub repository and in the Project panel files and folders are color coded accordingly. Therefore you can look for modified files (orange) and Undo the changes, and/or at new files you added (green) and eventually delete them (be careful with green folders as they represent both new folders as well as existing folders containing many files but only one is new). With this approach it is hard to undo and check out files that you may have deleted.

• Undo changes not yet committed with GitHub Desktop - If you have not yet committed your changes you can open GitHib Desktop, which will show you a summary f the changes in the Changes tab. To undo all changes, simply tick all the changes and then select Branch -> Discard All Changes... . To discard individual changes, simply right click on the change and and select Discard Change... in the pop-up menu. This will undo your changes whatever they are (deleted files will be restored in your local repository, newly created files will be deleted from your local repository, changes to existing files will be rolled back).

• Undo changes committed but not yet pushed with GitHub Desktop - If you have committed your changes but not yet pushed (GitHub Desktop will suggest you to Push origin) you will find an Undo button with the name of your latest commit below the blue button Commit to master. Simply click the Undo button and all the associated changes will re-re appear in the Changes tab. To discard uncommitted changes, refer to the instructions above. If you have committed changes multiple times in your local repository (not yet pushed to the online repository), you can still undo them one at the time starting from the most recent one (using the same Undo button). Since undoing a commit does not discard the changes, this is also a good strategy to merge multiple local commit into a single one before pushing to the online repository.

• Undo changes committed and pushed with GitHub Desktop - Changes pushed to the online repository can be reverted. However this should be a common practice but rather something you do in exceptional circumstances. Before pushing one or more commit, you must be absolutely confident with the changes you did. To undo changes in pushed in the repository, open the History tab in GitHub Desktop, find the commit you want to revert, right click on it and select Revert this Commit in the pop-up menu. Then click on Push origin or select Repository -> Push. Reverting a pushed commit leave some trace in the repository. Indeed the procedure just described creates an additional entry in the history of the repository in which the changes are complementary of those of the reverted commit (everything you added will be removed and viceversa). Indeed to further extend this concept, it will be possible in future to revert the reverting of a pushed commit. However, reverting a commit is not recommended, especially if the commit is not very recent. Indeed other users may had started developing upon the changes you made, and reverting them may create conflict when trying to push their changes (GitHub will guide you in resolving existing conflicts). If your commit included sensitive data you wish to permanently delete from the online repository, please get in touch with the repository administrator.

• Delete a published blog post - The easiest way to delete a blog post is to find the associated file.md and delete it from your local copy of the repository (you can do this in the Project panel of Atom or through the file manager of your computer). All multimedia files associated with the blog post and not used elsewhere must also be deleted from the /asset/image/ folder as well as from the UiO Vortex blog folder. Then open GitHub Desktop, commit and push the changes related to the files you removed. After the post will be no longer visible in the blog, but somehow the contents will still exist in the repository (all changes can be reverted through the History). If your post included sensitive data you wish to permanently delete from the online repository, please get in touch with the repository administrator.

• Removing your local copy of the repository - If you wish to remove your local copy of the repository, you open GitHub Desktop and select the mct-master.github.io in the Current Repository top-left menu, then select Repository -> Remove... . You can clone again the repository at anytime by following the instructions in Step 0. Do not attempt to remove the repository manually by deleting all files, because if this is done improperly and then inadvertently you push the changes you risk to remove everything from the online repository and consequently bring down the MCT Blog website (do not worry, we can still undo such a disaster!)

• Removing files UiO Vortex blog folder - Extra care must be used when deleting files from the UiO Vortex blog folder because history and restoring of deleted files is not supported. When you delete a file, it is gone forever. We recommend to double check the name of the file you are deleting and perhaps download the file on your computer before clicking on Delete (this allows to re-upload it if something went wrong). Never delete multiple files at the same time, and never delete folders, unless empty.

Strategies for collaborative blogging

The workflow described in Step 0 to Step 5 is suitable when working individually on a blog post as the sole author or as the author in charge of the post publishing. However, cross-campus teamwork is one of the key aspects of the MCT programme, therefore it is essential that you learn collaborate effectively with people in remote locations to you to produce contents for the MCT Blog.

When a team is working synchronously (i.e. at the same time) on the same blog post, the Live Share VS Code extension allows all team members to edit a markdown file at the same time. Obviously this require a prior agreement on who does what. Using Live Share is fairly easy, this video provides a live demonstration. With this approach, one team member creates the file.md on his local _posts_draft folder, and then he/she shares it with others using Live Share. Mind that the file.md will be only on the computer of one team member, which should also be in charge of previewing the post, moving it _posts folder finally publishing it.

When a team is working asynchronously (i.e. at different times) on the same blog post, we can rely on GitHub to collaborate on a blog post. Indeed Git repositories and other version control systems were initially introduced to facilitate collaborative software development (not very different from what we do here, it still involves editing and managing a large number of text files). In this approach, one team member creates the file.md on his local _posts_draft, include his share of the contents, then commit and push the changes to the repository. At different times, other team members will pull the repository (this will make the post file appear in their local _posts_draft folder), include their share of the contents, then commit and push the changes to the repository. Also this approach requires a prior agreement on who does what, and also a team member in charge of completing the workflow when the post is ready, which includes previewing the post, moving it _posts folder finally publishing it. Creating a branch and then merging it is another option (not described here), however this is not an overkill and it is nor recommended when working on a single blog post.

Skipping steps

When getting familiar with the MCT blogging tools, it is likely that you will start to follow your own workflow for creating and editing blog posts, which may be more practical and better aligns with your personal preferences and background. The guidelines in Steps 0 to 5 are not meant to be an absolute must. They are meant to be a straight forward list of steps to get you started with the MCT Blog. However a faster workflow should not come at the expenses of the sustainability of the blog, which means using different naming structures for the files and images, creating files where they are not supposed to be, uploading files exceeding the size limit, flooding the repository with multiple commits that could had been merged. The guidelines stated in this guide and in the Embedding and Storage of Files guide must be followed at all times. Posts on the MCT Blog are often part of the assessment in a course or in a module. Be aware that as described in the guide Blog Maintenance and Development, posts and files not compliant with the guidelines are periodically removed (either manually or automatically).

< Back to "How to use the MCT Blog"