Reformat remaining Markdown files

Author: RichDom2185

docs/src/modules/4-advanced/flow/flow.md

@@ -11,6 +11,7 @@
 6. Any tabs that need to be loaded will then be loaded, ready for display by the frontend.
 
 ## In the Frontend
+
 ![image](./fig2.png)
 > Figure 2: The Flow of the Source Modules system in the frontend
 

docs/src/modules/4-advanced/linting.md

@@ -3,6 +3,7 @@ order: 2
 ---
 
 # Code Formatting and Linting
+
 Code linting is the process of conducting static analysis on code to detect potential runtime issues and enforce
 stylistic conventions. Linting for the repository is provided by [ESLint](https://eslint.org).
 
@@ -11,31 +12,38 @@ stylistic conventions. Linting for the repository is provided by [ESLint](https:
 > removed from the Modules repository.
 
 ## Running ESLint
+
 ESLint can be run on its own on your bundle/tab code by using either of the following commands:
+
 ```sh
 yarn lint
 yarn buildtools lint .
 ```
 
 If you wish to run ESLint during the build process, you can instead use:
+
 ```sh
 yarn build --lint
 yarn buildtools build <bundle|tab> . --lint
 ```
 
 ## Disabling ESLint Rules
+
 If, for whatever reason you need to disable a specific ESLint rule for your bundle/tab, you can use the `// eslint-disable` directive. Please provide a short explanation on why
 the rule needs to be disabled, following the example provided below:
+
 ```tsx
 import { Button } from '@blueprintjs/core';
 // eslint-disable @typescript-eslint/no-var-requires This import doesn't work if written using ESM
 const TextBox = require('Textbox').default
 ```
 
 ## Ignoring Files
+
 By default, ESLint has been configured to not lint files in specific directories or matching specific patterns. You can see the ignore patterns in `eslint.config.js` under the section labelled "Global Ignores". Please
 note that if any of your code files matche these ignore patterns, they will not be properly linted by ESLint.
 
 ## Integration with Git Hooks
+
 Linting is run during the pre-push hook and also on pull-requests. Your code must not have any lint errors in order to be pushed to the
 branch and can have neither errors nor warnings to be merged.

docs/src/modules/4-advanced/manifest.md

@@ -2,6 +2,7 @@
 title: Modules Manifest
 ---
 # The Modules Manifest
+
 Every bundle has its own [manifest](../2-bundle/1-overview#manifestjson), but there is also a combined manifest, which actually consists of all the
 separate bundles' manifests combined into one. This serves as a easy file for `js-slang` to check against when loading bundles and also to make
 sure that the bundle being loaded actually exists.

docs/src/modules/4-advanced/testing.md

@@ -8,7 +8,7 @@ The testing library used by this repository is [`vitest`](https://vitest.dev).
 > [!IMPORTANT]
 > Other Source Academy repositories use `jest` as their testing package. Although `vitest` has been designed as a drop in replacement for `jest`,
 > there are subtle differences between the two. For example, `vi.spyOn` doesn't replace the implementation within the module while `jest.spyOn` does (See [here](https://vitest.dev/guide/mocking.html#mocking-pitfalls)).
-> 
+>
 > Refer to [this page](https://vitest.dev/guide/migration.html#jest) for more differences between `jest` and `vitest`.
 
 ## Adding Tests
@@ -17,6 +17,7 @@ By default, any Typescript (`.ts`) files located within a `__tests__` folder are
 detect any tests within that file, it will throw an error.  This also includes any subdirectories under a `__tests__` folder.
 
 Simply write your tests within a `__tests__` folder:
+
 ```ts
 // curve/src/__tests__/index.ts
 import { describe, expect, test } from 'vitest'; // You will need to import these functions, unlike in Jest
@@ -33,6 +34,7 @@ describe('This is a describe block', () => {
 > Javascript and Typescript declarations but will still conduct type checking for them.
 
 Tests for tabs can also use the `.tsx` extension along with JSX syntax:
+
 ```tsx
 // Curve/__tests__/index.tsx
 import { expect, test } from 'vitest';
@@ -52,16 +54,19 @@ For more instructions on how to write tests you can refer to the [Vitest website
 
 While writing tests, you might find that you might want to focus on a single test or single group of tests. For this, `vitest` provides on its `test`, `it` and `describe` functions
 a `.skip` and a `.only` property:
+
 ```ts
 describe('Test1 and Test3 will run!', () => {
   test('Test1', () => {});
   test.skip('Test2', () => {});
   test('Test3', () => {})
 });
 ```
+
 You don't have to comment out your tests; simply use `.skip` to indicate that a test block should not be executed.
 
 If for some reason you want to skip your tests based on some condition, `vitest` provides the `skipIf` property:
+
 ```ts
 describe('Test1 and Test3 will run!', () => {
   test('Test1', () => {});
@@ -71,13 +76,15 @@ describe('Test1 and Test3 will run!', () => {
 ```
 
 `.only` is kind of the reverse of `.skip`. Tests that you use `.only` with will be the **only** tests that run in that file:
+
 ```ts
 describe('Only Test 2 will run!', () => {
   test('Test1', () => {});
   test.only('Test2', () => {});
   test('Test3', () => {})
 });
 ```
+
 The main runner that runs unit tests on the CI/CD pipeline does not allow for `.only`. You can simulate this behaviour by running your tests with the
 `--no-allow-only` flag.  This behaviour is intended to prevent you from causing only part of your tests to run.
 
@@ -86,12 +93,14 @@ The main runner that runs unit tests on the CI/CD pipeline does not allow for `.
 > to remove `.only` before pushing to the main repository.
 
 Pushing with skipped tests however, is allowed. Do leave a comment explaining why the test is skipped:
+
 ```ts
 // Test is skipped because there is an outstanding bug
 test.skip('Test path resolution', () => {})
 ```
 
 ### Stubbing Tests
+
 If you want to indicate that tests should be written for certain functionality in the future, you can use `.todo`:
 
 ```ts
@@ -102,7 +111,9 @@ test.todo('Test path resolution')
 TODO tests still generate an entry in your test reports, but will be considered neither failed nor passed.
 
 ## Running Tests
+
 To run tests for a given bundle or tab, simply run either of the following commands within the directory:
+
 ```sh
 yarn buildtools test .
 yarn test # If your package.json has this script specified
@@ -115,13 +126,16 @@ You can also use `--update` to update snapshots and `--coverage` to run the V8 c
 For bundles and tabs, the test environment should always be `jsdom`, since they are intended for the browser.
 
 ## Integration with Git Hooks
+
 Any tests that you have written must be pass in order for you to push to the main repository, as well as for your pull requests to be merged.
 
 > [!TIP]
 > You can push to the branch while bypassing the Git hook by running:
+>
 > ```sh
 > git push --no-verify
 > ```
+>
 > However, the tests will still be run and must pass before your pull request can be merged. So, we recommend not using this option
 > unless absolutely necessary.
 
@@ -138,18 +152,21 @@ written in plain Javascript with a <nobr><code>// @ts-check</code></nobr> direct
 
 > [!WARNING] Dependency Optimization Error
 > You may find that when your tests run on your local machine the following warning (or something similar) may appear:
+>
 > ```sh
 > [vite] (client) ✨ new dependencies optimized: react/jsx-dev-runtime  
 > [vite] (client) ✨ optimized dependencies changed. reloading  
 > [vitest] Vite unexpectedly reloaded a test. This may cause tests to fail, lead to flaky behaviour or duplicated test runs.  
 > For a stable experience, please add mentioned dependencies to your config's `optimizeDeps.include` field manually.  
 > ```
+>
 > If this warning appears when you run your tests on the machine, you may find that your tests may still pass on the local machine, but
 > fail on the CI pipeline.
 >
 > This is because you have a dependency that Vite can only detect at runtime and so has to run its internal transforms twice. This causes
 > Vitest to fail, since the original import would have failed. To fix this, you should create your own `vitest.config.js` and add those
 > dependencies to `optimizeDeps`:
+>
 > ```js
 > export default defineProject({
 >   optimizeDeps: {
@@ -160,13 +177,15 @@ written in plain Javascript with a <nobr><code>// @ts-check</code></nobr> direct
 >   }
 > })
 > ```
+>
 > For more information, refer to the [Vite](https://vite.dev/config/dep-optimization-options.html#optimizedeps-include) documentation.
 
 Should you need to use a unique configuration, simply create your own `vitest.config.js` at the root of your bundle/tab.
 The configuration options in your `vitest.config.js` will be used **in addition** to the default options, so it is not necessary
 to redefine every single option in your configuration file.
 
 You should use the `defineProject` helper instead of the `defineConfig` helper:
+
 ```js [vitest.config.js]
 // @ts-check
 import { defineProject } from 'vitest/config';
@@ -183,13 +202,15 @@ There is no need to use `mergeConfig` to merge your configuration with the root
 the merging is performed automatically.
 
 ## Browser Mode
+
 Tabs have the ability to leverage `playwright` and `vitest`'s browser mode to ensure that the interactive features of the tab actually
 behave like they should.
 
 The default testing configuration for tabs has browser mode disabled. This is so that if your tab doesn't need the features that Playwright provides,
 `vitest` won't need to spin up the Playwright instance.
 
 ### Setting up Browser Mode
+
 Should you wish to enable browser mode, create a custom `vitest` configuration file for your tab with the `browswer.enabled` option set to `true`:
 
 ```js {9}
@@ -214,13 +235,15 @@ Now, the tests for your tab will be run in browser mode.
 > add more instances if necessary.
 
 ### Writing Interactive Tests
+
 Writing interactive tests is not very different from writing regular tests. Most of the time, the usual test and assertion functions will suffice.
 
 > [!INFO]
 > While writing your tests, you should use watch mode. This will allow `vitest` to open a browser and actually display what your tab looks like whilst
 > being rendered during the test.
 
 Use the `render` function provided `vitest-browser-react` to render your tab/component to a screen. The returned component can then be interacted with:
+
 ```tsx
 import { render } from 'vitest-browser-react';
 
@@ -233,13 +256,15 @@ test('Testing my component', () => {
   expect().somethingToHaveHappened();
 });
 ```
+
 `vitest` also provides [a different set](https://vitest.dev/guide/browser/assertion-api.html) of matchers that you can use specifically with browser elements.
 
 > [!TIP]
 > `vitest-browser-react` also provides a `cleanup` function that can be used after each test. You don't _technically_ need to use it, but
 > you may find that if you have multiple tests in the same file that behaviour might be inconsistent.
 >
 > You can use it with `afterEach` from `vitest`:
+>
 > ```ts
 > import { afterEach } from 'vitest';
 > import { cleanup } from 'vitest-browser-react';
@@ -248,6 +273,7 @@ test('Testing my component', () => {
 > ```
 
 ### `expect.poll` and `expect.element`
+
 Sometimes, visual elements take a while to finish or an element might take a while to load. If you just directly used an assertion, the assertion
 might fail because the element hasn't displayed yet:
 
@@ -263,6 +289,7 @@ test('An animation', async () => {
 ```
 
 Instead, `vitest` provides a special set of matchers that can be used to "retry" the assertion until it passes or when it times out:
+
 ```tsx
 import { render } from 'vitest-browser-react';
 
@@ -277,9 +304,11 @@ test('An animation', async () => {
 ```
 
 ### Animations with `requestAnimationFrame`
+
 If you're using `requestAnimationFrame` to trigger animations, you can also test the behaviour of these animated components.
 
 Firstly, add the following setup and teardown function calls to your code:
+
 ```ts
 import { beforeEach, afterEach, vi } from 'vitest';
 

docs/src/modules/4-advanced/typescript.md

@@ -4,7 +4,9 @@ Using the [`extends`](https://www.typescriptlang.org/tsconfig/#extends) property
 different levels to share options across both bundles and tabs.
 
 ## Missing types for dependencies and overriding `tsconfig.json`
+
 Sometimes, your bundle might depend on packages that have published their types differently. For example, the `communication` bundle requires `mqtt`:
+
 ```ts
 import { connect, type MqttClient, type QoS } from 'mqtt/dist/mqtt';
 // Need to use "mqtt/dist/mqtt" as "mqtt" requires global, which SA's compiler does not define.
@@ -16,7 +18,9 @@ export const STATE_OFFLINE = 'Offline';
 
 // ...other things
 ```
+
 The `mqtt` dependency however, is specified as such in `package.json`:
+
 ```json
 {
   "dependencies": {
@@ -25,6 +29,7 @@ The `mqtt` dependency however, is specified as such in `package.json`:
   }
 }
 ```
+
 The helpful comment below the import explains the discrepancy. Without further configuration, we find that Typescript is unable to find the types for the `mqtt/dist/mqtt` package:
 ![](./mqtt-types.png)
 

docs/src/repotools/index.md

@@ -3,6 +3,7 @@
 The `@sourceacademy/modules-repotools` package itself has a bunch of utilities for working with the repository.
 
 Below is a list of other tools:
+
 - [Development Server](./devserver/devserver)
 - [Docs Server](./docserver/1-overview)
 - [ESLint](./linting)

docs/src/repotools/linting.md

@@ -4,6 +4,7 @@ The ESLint config file for this repository is fairly complex. The different conf
 You can refer to [this](https://eslint.org/docs/latest/use/configure/configuration-files) page for more information on how ESLint processes these configuration objects.
 
 Generally, there are two types of linting rules:
+
 1. Repository only code (used for development of modules)
 2. Module code (Code that is actually intended to be used in Source)
 
@@ -14,6 +15,7 @@ ESLint does provide a configuration inspector which can be started using <nobr>`
 and also other information like what rules are considered deprecated.
 
 ## Configuration Conventions
+
 Our linting configurations often inherit from recommended configurations provided by plugins. However, not all of the rules that are configured by these configurations make sense
 for the repository at large. This requires that we manually override some of the settings provided by these configurations.
 
@@ -36,6 +38,7 @@ are usually incomplete snippets of Typescript/Javascript, so a lot of the typica
 -->
 
 ## Linting JSON Files
+
 For the most part, there are only stylistic rules that need to be applied to JSON files. This is why this repository doesn't use the official `@eslint/json` package for linting JSON files.
 Instead. the parser from `eslint-plugin-json` is used so that stylistic rules can be applied to the JSON files. This does mean that none of the rules from `@eslint/json` can be applied
 directly.

docs/src/repotools/vscode.md

@@ -1,14 +1,17 @@
 # VSCode Integration
+
 This page is dedicated to explaining all the VSCode integrations available from this repository.
 
 Since most developers here are assumed to be using Visual Studio Code, this repository automatically provides some extra tooling that integrates with VSCode, all found within the `.vscode` folder.
 
 ## JSON Schemas
+
 By default, VSCode doesn't apply any kind of validation to JSON files that don't have explicit schemas. Using the `settings.json` file, we can apply JSON schemas to specific JSON files.
 
 For this repository, this has been configured for `tsconfig.*.json` files to extend both the original `tsconfig` schema, but also to include the Typedoc schema. Bundle manifest files
 should also automatically receive validation and IntelliSense autocompletion.
 
 ## ESLint Validation
+
 By default, the VSCode ESLint extension doesn't also lint YAML files. This means that although ESLint will lint YAML files, the linting warnings and errors
 for YAML files will not appear in VSCode. Thus, we need to provide a specific configuration to tell the extension to lint YAML files.