Reformat more Markdown files

Author: RichDom2185

docs/src/modules/1-getting-started/6-troubleshooting.md

@@ -3,6 +3,7 @@
 ## Installation Troubleshooting
 
 ### ESBuild Error
+
 If you encounter errors with esbuild dependencies like the following while building:
 
 ```txt
@@ -17,6 +18,7 @@ Especially if you've worked with other Javascript/Typescript projects before, yo
 does not seem to work (or work permanently) for you.
 
 Things to check for:
+
 - Remove any errant `package.json` or `.yarnrc.yml` files in places like your home directory or elsewhere.
 - Run `npm uninstall -g yarn` if you previously installed Yarn using installed `npm`.
 - For people running Windows, `corepack enable` is a command that needs to be run using administrator privileges. If this is not possible for you, there are [workarounds](https://github.com/nodejs/corepack?tab=readme-ov-file#corepack-enable--name).

docs/src/modules/2-bundle/1-overview.md

@@ -2,11 +2,12 @@
 
 Similar to regular Javascript modules, Source allows developers to export functions and constants to users for importing into their programs.
 
-For example, the `binary_tree` module may want to provide an abstraction for Source programs to interact with the Binary Tree data structure. Thus, the `binary_tree` module would expose functions such as `make_tree`, `left_branch` and `right_branch` to be used in Source programs. 
+For example, the `binary_tree` module may want to provide an abstraction for Source programs to interact with the Binary Tree data structure. Thus, the `binary_tree` module would expose functions such as `make_tree`, `left_branch` and `right_branch` to be used in Source programs.
 
 ## Bundle Directory Structure Overview
 
 The typical bundle structure for a bundle is shown below. Each section will have its own explanation.
+
 ```dirtree
 name: bundle_name
 children:
@@ -65,12 +66,14 @@ export function createDrawFunction(
   // implementation hidden...
 }
 ```
+
 Note that `curve/functions.ts` exports both `createDrawFunction` and `make_point`.
 
 ```ts
 // curve/index.ts
 export { make_point } from './functions';
 ```
+
 However, only `make_point` is exported at the bundle's entry point however `createDrawFunction` is not, so cadets will not be able to access it, identical to how ES modules behave.
 
 ```js
@@ -87,6 +90,7 @@ It is not recommended that you use default exports in your code as default expor
 :::
 
 ## `package.json`
+
 The `package.json` file follows the same format as your typical `package.json` used with the likes of `npm` or `yarn`. If you use the template creation command, it should already have been created for you.
 
 ```jsonc
@@ -101,21 +105,27 @@ The `package.json` file follows the same format as your typical `package.json` u
   }
 }
 ```
+
 You can find more information about each of the fields and what they mean [here](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devdependencies).
 
 > [!WARNING] Bundle vs Package Name
 > The `name` field in `package.json` is the package name and must follow the format `@sourceacademy/bundle-[your bundle name]`.
 > The bundle name is what users will actually use to import your bundle from within Source code:
+>
 > ```ts
 > import { whatever } from 'bundle_name';
 > ```
+>
 > However, people consuming your bundle from regular Javascript and Typescript need to use the full (scoped) package name:
+>
 > ```ts
 > import { whatever } from '@sourceacademy/bundle-bundle_name';
 > ```
 
 ### `manifest.json`
+
 `manifest.json` contains the information required by `js-slang` to load your bundle.
+
 ```jsonc
 {
   "tabs": ["Curve"], // String array of the names of the tabs that will be loaded alongside your bundle
@@ -133,7 +143,9 @@ Your bundle may rely on features that are only present in later Source Chapters.
 > You can use the `buildtools list bundle` command to check that your bundle can be properly detected and has the correct format.
 
 ## `tsconfig.json`
+
 This file controls the behaviour of Typescript. By default, it should look like this:
+
 ```json
 {
   "extends": "../tsconfig.json",
@@ -148,10 +160,9 @@ This file controls the behaviour of Typescript. By default, it should look like
   }
 }
 ```
+
 In general, there should not be a need for you to modify this file.  A full explanation on how to use `tsconfig.json` can be found [here](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). Note that the `typedocOptions` field is a custom field used by `typedoc` for its configuration. Refer to [here](https://typedoc.org/documents/Options.Configuration.html#compileroptions) for more information.
 
 > [!WARNING]
 > You should not remove or modify the `typedocOptions` section from your `tsconfig.json` unless you provide the name of your bundle to Typedoc via its other configuration methods. Generating documentation for your bundle
 > requires that the name of your bundle be set correctly.
-
-

docs/src/modules/2-bundle/3-editing.md

@@ -1,23 +1,29 @@
 # Editing an Existing Bundle
+
 This page contains instructions for modifying an existing bundle. If you are creating a new bundle from scratch, refer to [these](./2-creating/2-creating) instructions instead.
 
 ## Installing Dependencies
+
 To install **only** the dependencies required by the bundle you are modifying, use the command below:
 
 ```sh
 yarn workspaces focus @sourceacademy/bundle-[desired bundle]
 ```
 
 ## Adding Dependencies
+
 Your bundle may need other Javascript packages. To add a dependency to your bundle, run the command below:
+
 ```sh
 yarn add [dependency]
 ```
 
 If the dependency does not need to be present during runtime, then use:
+
 ```sh
 yarn add --dev [dependency]
 ```
+
 This adds the dependency to `devDependencies` instead.
 
 > [!WARNING]
@@ -27,18 +33,22 @@ This adds the dependency to `devDependencies` instead.
 > [!NOTE]
 > There are certain dependencies that are common to all bundles (like `react`). When adding such a dependency, remember to add the exact version
 > specified in the root repository `package.json`:
+>
 > ```sh
 > yarn add react@^18.3.1
 > ```
+>
 > You can also use the command `yarn constraints`  to check if you have incorrectly specified the version of a dependency.
 
 > [!NOTE]
 > When adding dependencies that originate from the repository (e.g `@sourceacademy/modules-lib`), use `workspace:^` as the given version:
+>
 > ```sh
 > yarn add @sourceacademy/modules-lib@workspace:^
 > ```
 
 ### React Within bundles
+
 Currently, the way bundles are loaded by `js-slang` means that React cannot be externalized for bundles. `js-slang` simply has no way to provide React
 from the frontend to the bundle.
 
@@ -47,12 +57,15 @@ This means that tools like the React DevTools will not be able to work correctly
 Refer to the [issue](https://github.com/source-academy/modules/issues/211) tracking this functionality.
 
 ## Bundle Conventions
+
 To ensure that bundles conform to the different Source language specifications, there are a few rules that bundles need to abide by.
 Refer to [this list](./4-conventions/index) for more information.
 
 ## Common Modules Library
+
 There are common functions such as `hexToColor` available in the Common Modules Library. You can make use of these functions
 instead of implementing your own versions of them.
 
 ## Adding Unit Tests
+
 Where possible, you should add unit tests to your bundle. Refer to [this](/modules/4-advanced/testing) page for instructions.

docs/src/modules/2-bundle/4-conventions/1-basic.md

@@ -1,8 +1,10 @@
 # Basic Conventions
 
 ## 1. Cadet facing functions should not have default or rest parameters
+
 The function signature below takes in two booleans, the second of which is optional. This is not supported for Module functions in Source, but is fine if your function
 isn't being exposed to cadets.
+
 ```ts
 // Don't expose this to cadets!
 function configure_options(option_1: boolean, option_2: boolean = false) {
@@ -26,22 +28,28 @@ Neither default nor rest parameters are currently supported due to an [issue](ht
 :::
 
 ## 2. If your bundle requires specific Source features, make sure to indicate it in the manifest
+
 Consider the bundle function below:
+
 ```ts
 export function sum(args: numbers[]) {
   return args.reduce((res, each) => res + each, 0);
 }
 ```
+
 It takes an an input an array of `number`s. However, arrays are only available in Source 3 onward. This means that you should indicate in your bundle's manifest:
+
 ```jsonc
 {
   "requires": 3
 }
 ```
+
 to let `js-slang` know that your bundle can't be loaded with Source 1 and 2.
 
 ::: details Which data structure to use?
 In the above example, the array can actually be replaced with a Source `List`:
+
 ```ts
 import { head, tail } from 'js-slang/dist/stdlib/list';
 
@@ -59,11 +67,13 @@ export function sum(args: List) {
   return total;
 }
 ```
+
 Lists are actually introduced in Source 1, which would make the above function compatible with Source 1 instead of requiring Source 3. If your bundle doesn't need
 functionality specific to arrays, then consider using Source Lists instead.
 :::
 
 ## 3. Making use of `js-slang/stdlib`
+
 Bundles, where necessary, should use the implementations of libraries such as `list` or `stream` from the `js-slang` standard library:
 
 ```ts
@@ -77,6 +87,7 @@ export function is_sound(obj: unknown): obj is Sound {
   );
 }
 ```
+
 These libraries get externalized and are then provided to bundles at runtime, so not only does this make your bundle size smaller, but it also
 ensures that you are using the same version of the `stdlib` as the version being used by `js-slang` while running your bundle code.
 

docs/src/modules/2-bundle/4-conventions/2-abstractions.md

@@ -9,13 +9,15 @@ primitive and non primitive objects (`Wave`s are `(t: number) => number` while `
 Instead of passing around the type in terms of primitives, you should make it such that cadets interact directly with the abstraction instead. Take the `sound` bundle for example.
 
 `Sound`s are defined as a `pair`, where the head is a `Wave` and the tail is a number representing the duration of that sound:
+
 ```ts
 import type { Pair } from 'js-slang/dist/stdlib/list';
 
 type Sound = Pair<Wave, number>;
 ```
 
 Functions from the `sound` bundle interact directly with `Sound`s, rather than the underlying type:
+
 ```ts
 // Do this!
 export function play_in_tab(sound: Sound): void {
@@ -31,12 +33,14 @@ export function play_in_tab(sound: Pair<Wave, number>): void {
 Functionally, `Sound` behaves like a primitive type: as far as a cadet using the `sound` bundle is concerned, the bundle allows them to make and manipulate `Sound`s.
 
 ## Breaking Abstractions with `display` and `stringify`
+
 `js-slang` provides a built-in function for converting any value into a string: `stringify()`. `display()` behaves like the typical `console.log` and prints the string representation
 as returned by `stringify` to the REPL. Under the hood, `stringify` uses the default Javascript `toString` functionality to convert primitive types to their string representations. This does
 mean that for "primitives" that are actually objects, `js-slang`'s default implementation will end up exposing implementation details.
 
 Taking an example from the `curve` bundle, `RenderFunction`s are considered a type of primitive. Without any further changes, calling `display` on a `RenderFunction` produces the following
 output:
+
 ```js
 // Partial toString() representation of a RenderFunction
 curve => {
@@ -47,11 +51,14 @@ curve => {
   return curveDrawn;
 }
 ```
+
 This exposes implementation details to the cadet and "breaks" the `RenderFunction` abstraction. Thus, there is a need for such objects to be able to override the default `toString`
 implementation.
 
 ## The `ReplResult` interface
+
 To allow objects to provide their own `toString` implementations, objects can implement the `ReplResult` interface:
+
 ```ts
 interface ReplResult {
   toReplString: () => string
@@ -69,22 +76,28 @@ but if your circumstances can't support it you can refer to the second method wh
 
 > [!TIP]
 > Source automatically hides the implementation for all functions at the top-level of a bundle. Running the code below
+>
 > ```ts
 > import { show } from 'rune';
 > display(show);
 > ```
+>
 > produces the following string output:
+>
 > ```txt
 > function show {
->	 [Function from rune
+>  [Function from rune
 >      Implementation hidden]
 > }
 > ```
+>
 > This means that is is unnecessary to implement `ReplResult` for any of your top-level functions. You can still override this automatic functionality by implementing
 > `ReplResult`.
 
 ### Implementing `ReplResult` directly
+
 The simplest way to implement the interface is to do it in Typescript. For example, the `curve` bundle has a `Point` class, which is an abstraction of a point in 3D space with a color value:
+
 ```ts
 /** Encapsulates 3D point with RGB values. */
 export class Point implements ReplResult {
@@ -105,9 +118,11 @@ would result in the infamous `[object Object]` being printed.
 The benefit of implementing the interface this way in Typescript is that it enables type-checking to ensure that the interface is properly implemented.
 
 ### Implementing `ReplResult` indirectly
+
 The `ReplResult` type is only just a Typescript interface. So long as `toReplString` property is present on the object/function, `js-slang` will be able to call it.
 
 Referring back to the `curve` bundle's `RenderFunction`s, the type `RenderFunction` is really just a plain Javascript function with some extra properties attached to it:
+
 ```ts
 type RenderFunction = {
   (func: Curve): CurveDrawn
@@ -119,6 +134,7 @@ type RenderFunction = {
 ```
 
 This type doesn't implement the `ReplResult` interface, but before `RenderFunction`s are returned, they have the `toReplString` property set:
+
 ```ts
 // curve/src/functions.ts
 
@@ -156,13 +172,15 @@ function createDrawFunction(
 // This has type (points: number) => RenderFunction
 export const draw_connected = createDrawFunction('none', 'lines', '2D', false);
 ```
+
 > [!TIP]
 > Notice in this case that they abstraction is being applied to the return type of `draw_connected` and not to the return type of `createDrawFunction`. The latter
 > is just a factory function for creating the different `draw_connected` function variants, each of which return `RenderFunction`s.
 >
 > As mentioned earlier, since `draw_connected` is exported at the top-level of the `curve` bundle, `ReplResult` is automatically implemented for it.
 
 We've seen the result of the default `toString` implementation. By providing `toReplString`, `js-slang` can instead return a user-friendly stringified representation of a `RenderFunction`:
+
 ```js
 import { draw_connected } from 'curve';
 display(draw_connected(200));
@@ -179,23 +197,30 @@ provide compile time validation that the property has been set correctly.
 > interface, so there should be no need for this, but this section is here as a "just in case".
 
 ## Simple Abstractions
+
 There may be cases where you intend for your abstraction to be "decomposable" by cadets. The `Sound` type is just a wrapper around a `js-slang` pair:
+
 ```ts
 type Wave = (t: number) => number
 type Sound = Pair<Wave, number>
 ```
+
 For both of these types, the default `toString` behaviour closely follows their definitions:
+
 ```ts
 const s = make_sound(t => 0, 1000);
 display(s);
 // Produces the output below
 // [t => t >= duration ? 0 : wave(t), 100]
 ```
+
 Calling `display` on a `Sound` prints out a pair consisting of a function and a number. In this case, then, it becomes unnecessary to apply abstractions and implement the `ReplResult` interface.
 
 ## Avoid using raw object literals
+
 Object literals are not supported in Source, but might be required in bundle code. For example, in the case where your bundle might have several configurable options that the cadet can change,
 you should have a function for each option rather than a single function that takes all the options:
+
 ```ts
 // Do this!
 export function change_text_color(color: string): void;
@@ -210,6 +235,7 @@ export function change_text_options(options: TextOptions): void
 ```
 
 Alternatively, you could do something like this:
+
 ```ts
 interface TextOptions {
   color: string
@@ -222,4 +248,5 @@ export function change_text_options(options: TextOptions): void
 const options = create_text_options('blue', 20);
 change_text_options(options);
 ```
+
 The idea is that the abstraction of the `TextOptions` type is never broken and that the cadet never interacts with the object directly.