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.
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 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
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." ---
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 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:
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.