I finally had a chance to work on IPC144, an Open Educational Resources (OER) project with a view to modernizing the old IPC144 course website with Docusaurus. As a first time contributor, I found a perfect issue to get familiar with the project: auditing and fixing the automatically translated Markdown files.
Getting started
As instructed in the meta issue, I opened a new issue for the page on which I'd like to work. Once I'd cloned the repository, I could immediately start auditing the Markdown file without any additional configuration. I had to go over a long checklist posted in the meta issue, but I'll discuss what I've found interesting in this blog.
Docusaurus Features
Docusaurus has 2 distinct features that can significantly improve the old IPC144 website:
- Frontmatter: the top section of a content file used for specifying metadata and Docusaurus's configuration variables
- Admonition: a highlighted section in a content file
Frontmatter
Docusaurus supports a large number of Frontmatter fields. I added 4 of them to the Markdown file for SEO optimization:
---
id: algorithms
...
title: "Algorithms"
slug: /refinements/algorithms
description: "An algorithm is the set of rules that define the sequence of operations required to complete the task."
---
Admonition
There were some noteworthy sections of the page. However, they barely stood out because of the use of Markdown blockquote like this:
Luckily, Docusaurus' Admonition is perfect for this role. It is really eye-catching and easy to use. For example, I can enclose the content with :::note and ::::
:::note
The value returned by `find()` (variable `i`) is validated to ensure that it is within the bounds of the key array (that is, we check that it is not -1 and not more than the number of items in the array).
:::
and it will be rendered like this:
Final thoughts
Although it might seem like a small issue, it's still very satisfying to know that my contribution can enhance the learning experience of other fellow students.
Issue: https://github.com/Seneca-ICTOER/IPC144/issues/28
PR: https://github.com/Seneca-ICTOER/IPC144/pull/72
Docusaurus: https://docusaurus.io/docs
Top comments (0)