Markdown file auditing: what I learned.
Tags: opensource, markdown
Published: 2021-11-16 17:18:52

#### C Programming At Seneca

For the longest time, the C Programming class notes at Seneca were hosted on a [website](https://ict.senecacollege.ca/~ipc144/pages/content/index.html). However, given the development in web technologies and frameworks since their creation the professors and heads at Seneca have decided to reformat the notes into Markdown using [Docusaurus](https://docusaurus.io/). 

Because this a huge undertaking, and we're all learning software development which includes documentation writing, the job of auditing the new Markdown files has come to us students.

#### What are we looking for?

Generally the automatic conversion tool did a good job of taking the website notes and creating Markdown files. The files were added to Docusaurus and include dark mode. However, some things it missed or converted to non-standard ways of writing Markdown.

For example, in the file I audited called [functions.md](https://github.com/Seneca-ICTOER/IPC144/issues/26) the images were loaded properly using Docusaurus. **But** because the original website did not have dark mode capability, the images backgrounds were not adjusted. This lead to issues like black arrows on a black background:

###### Before
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3a0pi6e7kcosb1o33jwg.png)

How I fixed it was using a `<span>` element around the images on the page with the class name `mdImg`. Inside the global CSS file I added a selector of `.mdImg > p > img` and changed the background color to white `background-color: #ffffff;`. I used a `<span>` because they are inline as opposed to `<div>` which is block-level and may mess with responsiveness accidentally.

###### After
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wdf0w3fvx8d5kqa720ah.png)
 

#### React specific changes

Since Docusaurus is built using React, and the original website was made using HTML/CSS. As such, when the HTML elements were rendered they used `class` and `colspan`. React uses `className` and `colSpan`. It didn't cause a direct error, but my friend [Kevan Yang](https://github.com/Kevan-Y) pointed out it had many console errors so I changed all the classes. Furthermore, it didn't cause an error again but the `<tr>` elements needed a matching `<thead>` and `<tbody>`:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yipcfsagu5ixnmkfy03f.png)
 
You may also notice that I removed spaces before `<tr>` because that's another issue in React rules that `<tr>` can't have blank spaces before or between it. 

#### Other small fixes

Some smaller fixes included fixing the mispelling "parameter", adding alt tags to images, and adding Markdown admonitions for notes instead of blockquotes.

I also removed inline CSS that was causing table backgrounds to be yellow even in dark mode:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ccmhk25fojk6fxd5anlo.png)
 
#### What I learned

Auditing the file taught me a lot about attention to detail, in large part due to my friends code reviewing the pull request. I caught a lot of the issues myself at first, but things like the console error and the image in dark mode being incompatible I learned a lot about researching how to fix issues I haven't encountered before.