DEV Community

Cover image for Audit and Fix a Markdown Page
MizuhoOkimoto
MizuhoOkimoto

Posted on

Audit and Fix a Markdown Page

My recent contribution to an open source project is the improvement of the online course notes for the C language course (IPC144) in my college. The online note uses Docusaurus, and I had the opportunity to study Docusaurus a while back, so this contribution deepened my knowledge.

Issue

The issue I worked on was the Audit and Fix a Markdown Page. Each chapter of that online note consists of its own md file. My professor file an issue with a list of all of the md files and 19 tasks for improving each page. I selected the "output-functions" page in it, filed a new issue, and worked on the tasks.

Checking display

I set everything up locally and checked for problems with the display. Such as: typo, markdown, the Light and Dark mode, and the desktop and mobile.

Using tools for improving the quality of web pages

As my professor mentioned, I tried running the page through Lighthouse and Web Hint.
I had never used them, but it was easy to check with those tools.
Lighthouse checked if the page is optimized for each item, and showed me there is no alt tag for images. After I added alt, performance, accessibility, best practices, SEO scores went up.
lighthouse
When I checked the page using Web Hint, I got 55 hints, but nothing about the page I was working on.
Web Hint

Fixing Frontmatter for the page

Markdown documents can use the Markdown FrontMatter metadata fields, enclosed by a line --- on either side.(Docusaurus official page)
I added the FrontMatter below:

---
sidebar_position: 5
title: Output Functions
id: output-functions
slug: modularity/output-functions
desctiption: This chapter on output functions is about invoking standard library procedures to stream data to users
---
Enter fullscreen mode Exit fullscreen mode

Reviewed from other students

I made a PR, other students reviewed it and gave me some requests.
They were:

  • Removing extra space I missed in the md file
  • Adding a hyperlink to a related page
  • Adding Description to the page(as a Frontmatter)
  • Adding backticks to function names

Conclusion

I thought there were a lot of tasks, but it wasn't too difficult. It was good to be able to contribute to the project that actually used Docusaurus and to experience the improvement of the page using Lighthouse and Web Hint. This time, my professor listed the tasks and provided them to us, which made the contribution easier, and I would like to use the task when working on external issues myself in the future.

🔗Links

IPC144 Project repo | Issue | Pull Request

(Photo by Glenn Carstens-Peters on Unsplash)

Discussion (0)