How to use the MCT Blog ‐ Blog Maintenance and Development - MCT-master/guides GitHub Wiki
< Back to "How to use the MCT Blog"
The MCT Blog is based on Github Pages. GitHub Pages is a static web hosting service offered by GitHub for hosting blogs or project documentation. All GitHub Pages content is stored in Git repository, either as files served to visitors verbatim or in Markdown format. GitHub is seamlessly integrated with Jekyll static web site and blog generator and GitHub continuous integration pipelines (not used). Each time the content source is updated, Jekyll regenerates the blog and automatically serves it via GitHub Pages infrastructure.
Using a blog based on Github Pages allows for both ease of use and for advanced web development through a variety of languages in individual posts as well as for the organization of the entire blog. By using the MCT Blog you will get familiar with several professionally-relevant tools.
When developing the blog locally on your computer, it is important to match the dependencies and versions used in GitHub Pages, which are usually older but more stable released of Jekyll plugins and themes. For instance, if you plan to develop new functionality for the blog that is based on a specific Jekyll plugin, you need to ensure that the same version of the plugin is available in the GitHub Pages infrastructure.
All configuration options of the MCT Blog are specified in the _config.yml file in the root folder of the repository. In particular, the blog uses the minima theme. The file /assets/main.scss includes presentation and style options that override the defaults in the minima theme. Also, the file '/_includes/social.html' has been included in the blog repository to override the default one (Youtube channels was not supported). The files '/_includes/site-search.html', '/utils/search.json', and '/utils/fetch.js' have been added to implement the blog search function.
The current version of minima used in GitHub Pages is 2.5.1 which source code is available here. The source code is automatically imported when building the blog using Jekyll (both locally and on GitHub pages servers), there is no need to download it or include it anywhere. However, at times it may be useful to inspect the source code of the theme (especially the contents of the _sass folder) in order to understand how to better implement certain changes or improvements.
Finally, the folder utils includes additional scripts and utilities to enhance blog's functionality, usability and appearance, as detailed in the associated readme file.
Maintenance
The following maintenance tasks should be performed every quarter:
- delete outdated drafts in the folder
_posts_draft - find and resize large files in the folder /assets/images
- find for files not properly named or not placed in the right folder of both GitHub repository and UiO Vortex blog folder (ask the author to implement changes when needed)
- find and delete inappropriate files (if the file is particularly large notify the MCT Programme Coordinator because the file must be removed from the repository's history)
- check the consistency of all latest post from the last quarter (inspect from the blog homepage, ensure that all posts have date, title, authors, excerpt, and a reasonably sized featured image )
- once a year reduce the repository overall size by removing files larger than 500 KB from the history (must be done by the MCT Programme Coo using git filter-branch)
The various .gitignore files in the various folders of the repository and the pre-commit hook should help in preventing that files or files not properly named are committed and pushed in the repository.
Development
Fixing bugs, improving existing features or adding new ones are activities continuously carried out by users of the MCT Blog. If you find anything wrong or if you have suggestions, open an issue in the blog repository and include appropriate labels. If you open an issue, you should also take the lead or contribute towards resolving it.
When modifying the blog source code, you should always carry out extensive testing on your local copy built with Jekyll before pushing the changes to the online repository. Major modifications to the blog theme, layout, organizations, must always be approved by the community of users.
If you want to experiment with the development of the MCT Blog, it is recommended that you fork the repository into your account, where you can mess it up as much as you want. If you think that you have implemented something worth integrating in the MCT Blog, you can eventually submit a pull request. We do not recommend creating and working on branches. Although your GitHub account has sufficient credentials for merging branches and for approving push requests, you should always discuss the changes you are proposing with other users of the MCT Blog and with the MCT Programme Coordinator before including these in the master branch (which is the branch from which GitHub Pages takes the contents to build the static version of the blog). For minor bug fix, or for modification already extensively discussed in the issue tracking system there is no need for approval by users and administrators.