Add new "Explore Codebase" page for DG

docs/_markbind/layouts/devGuide.md

@@ -16,6 +16,7 @@
   * [Implement a New Feature]({{baseUrl}}/devGuide/bootcamp/implementAFeature.html)
 * Development :expanded:
   * [Setting up]({{baseUrl}}/devGuide/development/settingUp.html)
+  * [Exploring Codebase]({{baseUrl}}/devGuide/development/exploringCodebase.html)
   * [Workflow]({{baseUrl}}/devGuide/development/workflow.html)
   * [Writing Components]({{baseUrl}}/devGuide/development/writingComponents.html)
   * [Writing Plugins]({{baseUrl}}/devGuide/development/writingPlugins.html)

docs/devGuide/bootcamp/exploreMarkBind.md

@@ -349,22 +349,28 @@ You now have modified some of the commonly adjusted site structure and configura
 MarkBind sites can be easily deployed with CLI commands or via CI. Let's try deploying our site via GitHub Actions.
 
 1. Open the `site.json` file in your `mb-dev-xxx` folder.
-1. Change `"baseUrl": "",` to `"baseUrl": "/mb-dev-xxx",` (Note the leading `/` and that the value is the same as your GitHub repository name).
-1. Create a `.github/workflows/deploy.yml` file with the following content mentioned in the <a tags="environment--combined" href="/userGuide/deployingTheSite.html#deploying-via-github-actions">GitHub Actions guide</a><a tags="environment--dg" href="https://markbind.org/userGuide/deployingTheSite.html#deploying-via-github-actions">GitHub Actions guide</a>.
+2. Change `"baseUrl": "",` to `"baseUrl": "/mb-dev-xxx",` (Note the leading `/` and that the value is the same as your GitHub repository name).
+3. Create a `.github/workflows/deploy.yml` file with the following content mentioned in the <a tags="environment--combined" href="/userGuide/deployingTheSite.html#deploying-via-github-actions">GitHub Actions guide</a><a tags="environment--dg" href="https://markbind.org/userGuide/deployingTheSite.html#deploying-via-github-actions">GitHub Actions guide</a>.
    1. Note that you should change `branches: master` to `branches: main` if you are using the `main` branch.
 
 <panel src="{{baseUrl}}/userGuide/deployingTheSite.md#markbind-action-tip" header="**MarkBind Action**" type="info" expanded/>
 
-4. Ensure that you have added your remote GitHub repository to your local repository with the following command (replace `xxx` with your GitHub username):
+4. Update you GitHub repository settings to enable read and write permissions for Actions.
+   1. Navigate to the Settings > Actions section.
+   2. Under `General` tab, find the `Workflow permissions` section.
+   3. Click to toggle to `Read and write permissions`.
+   4. Save by clicking on the `Save` button.
+
+5. Ensure that you have added your remote GitHub repository to your local repository with the following command (replace `xxx` with your GitHub username):
     ```bash
     git remote add origin https://github.com/xxx/mb-dev-xxx.git
     ```
-5. Commit and push the changes to the `main` branch with the following commands:
+6. Commit and push the changes to the `main` branch with the following commands:
     ```bash
     git add .
     git commit -m "Update content"
     git push origin main
-6. Update your GitHub repository setting for deploying to GitHub Pages.
+7. Update your GitHub repository setting for deploying to GitHub Pages.
    1. Navigate to the Settings > Pages section on GitHub for that repository and set the source to `Deploy from a branch` and the branch to `gh-pages` and `/(root)`.
 
 <box type="important" light>

docs/devGuide/design/projectStructure.md

@@ -14,6 +14,8 @@
 This page gives you an overview of the MarkBind's internal project structure.
 </div>
 
+<div id="packages-overview">
+
 ## Packages
 
 The MarkBind project is developed in a <tooltip content="We follow a monorepo approach, similar to Babel and other open source projects. To see a discussion on the pros and cons of this approach, read [here](https://github.com/babel/babel/blob/main/doc/design/monorepo.md).">monorepo</tooltip> ([MarkBind/markbind](https://github.com/MarkBind/markbind)) of 4 packages:
@@ -145,6 +147,7 @@ Some custom components and directives are also added for MarkBind's use.
   * TabGroup.vue
 
   * Tabset.vue
+</div>
 
 {% from "njk/common.njk" import previous_next %}
 {{ previous_next('../development/migratingToTypeScript', 'architecture') }}

docs/devGuide/development/exploringCodebase.md

@@ -0,0 +1,161 @@
+{% set title = "Exploring Codebase" %}
+<span id="title" class="d-none">{{ title }}</span>
+
+<frontmatter>
+  title: "{{ title }}"
+  layout: devGuide.md
+  pageNav: default
+</frontmatter>
+
+# {{ title }}
+
+<div class="lead">
+This page provides an overview of the MarkBind codebase and innovative methods to explore it as an onboarding developer.
+</div>
+
+## TL;DR
+
+- [ ] Overarching structure of the MarkBind codebase
+- [ ] Stepping through the codebase with a debugger
+- [ ] Ingesting the codebase with LLMs
+
+## Overarching Structure of the MarkBind Codebase
+
+<panel src="{{baseUrl}}/devGuide/design/projectStructure.md#packages-overview" header="**Project Architecture**" type="info" no-close bottom-switch></panel>
+
+<br>
+
+## Debugger Setup
+
+After setting up an experimental MarkBind site, you can step through the codebase with a debugger to understand the flow of the codebase.
+
+<tabs>
+<tab header="Visual Studio Code">
+
+First, we will set up a **VS Code debug configuration**. This will allow us to configure and save setup details while debugging. If not already done so, set up a new `Node.js` debugger as shown below, which will create a new template `.vscode/launch.json` file for you to get started.
+
+![]({{baseUrl}}/images/debugger/VSCode_1.jpg) {.ms-4}
+
+Next, we will configure the `.vscode/launch.json` file to use some sample configurations as a baseline. These configurations specify specific application entry points as well as runtime arguments. Feel free to tweak them as you see fit. 
+
+<panel header="Sample Config - Markbind Documentation as a development environment">
+
+In this configuration, we simulate running `markbind serve -o -d` on MarkBind's documentation as a development environment. Here, notice we specify the following runtime arguments:
+* the <a tags="environment--combined" href="/userGuide/cliCommands.html#serve-command">lazy reload`-o`</a><a tags="environment--dg" href="https://markbind.org/userGuide/cliCommands.html#serve-command">lazy reload`-o`</a> option to speed up page building
+* the `-d` developer option. 
+
+```json {.ms-4 heading="launch.json"}
+{
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Dev Docs",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "cwd": "${workspaceFolder}/docs",
+            "program": "${workspaceFolder}/packages/cli/index.js",
+            "args": ["serve", "-o", "-d"]
+        }
+    ]
+}
+```
+</panel>
+
+<panel header="Sample Config - General Debugging of MarkBind Tests">
+
+In this configuration, we will simulate running `npm run test` on MarkBind's packages. This allows us to step through the testing done in the various packages in MarkBind.
+
+```json {.ms-4 heading="launch.json"}
+{
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "test",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "cwd": "${workspaceFolder}",
+            "runtimeExecutable": "npm",
+            "runtimeArgs": ["run", "test"]
+        }
+    ]
+}
+```
+</panel>
+
+<panel header="Sample Config - Specific Debugging of MarkBind-CLI Package Tests">
+
+In this configuration, we will simulate running `npm run test` on MarkBind's `CLI` package. Notice that the application entry point has been updated to reflect this. 
+
+```json {.ms-4 heading="launch.json"}
+{
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "test cli",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "cwd": "${workspaceFolder}/packages/cli",
+            "runtimeExecutable": "npm",
+            "runtimeArgs": ["run", "test"]
+        }
+    ]
+}
+```
+</panel>
+
+<br>
+
+You can add **multiple configurations** as needed in debugging, each with their own respective application entry points, runtime arguments, and environment variables. 
+
+![]({{baseUrl}}/images/debugger/VSCode_2.jpg) {.ms-4}
+
+After setting up the appropriate configurations, **set up breakpoints** in your code to tell the debugger to pause execution when it reaches that line. You can set breakpoints by clicking in the gutter next to the line number in the editor. For more information about breakpoints, see [VSCode: Working with Breakpoints](https://code.visualstudio.com/docs/editor/debugging#_breakpoints).
+
+Next, start a **debugging session** by selecting the desired debug configuration, and clicking run. 
+* The Debug console at the bottom of the window will be displayed, which shows the debugging output. 
+* The Debug toolbar at the top of the window allows you to control the flow of the debug session, such as stepping through code, pausing execution and stopping the session.
+* The Variables section of the Run and Debug view allows inspection of variables and expressions relative to the selected stack frame in the Call Stack section.
+
+![]({{baseUrl}}/images/debugger/VSCode_3.jpg) {.ms-4}
+
+To **learn more** about debugging with Visual Studio Code, refer [here](https://code.visualstudio.com/docs/editor/debugging) for a more extensive official guide on debugging in VS Code. 
+
+</tab>
+<tab header="JetBrains IDEs">
+    <box type="info">
+        <markdown>Tested on JetBrains IDEs version `2024.1.1` and above.</markdown>
+    </box>
+    <markdown>1. Navigate to `Run` > `Edit Configurations...`.</markdown>
+    <markdown>2. Click the `+` icon and select `Node.js`.</markdown>
+    <markdown>3. Set the `Working directory` to the root of the MarkBind test site.</markdown>
+    <box type="tip"><markdown>Set the `Working directory` to `markbind/docs` to experiment with the MarkBind documentation site.</markdown></box>
+    <markdown>4. Set the `File` to the <trigger for="pop:absolute_path">**ABSOLUTE PATH**</trigger> of `packages/cli/index.js`.</markdown>
+    <popover id="pop:absolute_path" content="e.g. ~/Documents/markbind/packages/cli/index.js"></popover>
+    <markdown>5. Set the `Application parameters` to <trigger for="modal:serve-arguments" trigger="click">`serve -d -o`</trigger>.</markdown>
+    <modal id="modal:serve-arguments" center large>
+        <include src="{{baseUrl}}/userGuide/cliCommands.md#serve-command"></include>
+    </modal>
+    <markdown>6. Name the configuration and click `OK`.</markdown>
+    <markdown>7. Add breakpoints to the lines you want to inspect.</markdown>
+    <markdown>8. Select the configuration from the dropdown next to the "run" button and click the "debug" button to start tracing.</markdown>
+</tab>
+</tabs>
+
+These steps should allow you to easily start debugging and gain deeper insights into MarkBind’s internal code flow and behavior. With breakpoints, step-through execution, and variable inspection, you will be able to:
+
+* Understand how different parts of the code interact,
+* Trace bugs or unexpected behavior more efficiently,
+* Experiment with changes in a controlled environment.
+
+
+## Ingesting the Codebase with LLMs
+
+[//]: # (TODO: Add content)
+
+

docs/devGuide/development/workflow.md

@@ -156,7 +156,7 @@ You can run `npm run build:backend` in the root directory to compile the files,
 
 1. Configure your IDE to perform automatic compilation on file change/save. (_Recommended for general development_)
 
-   Refer to your IDE's guides to set this up. For instance, here are the guides for [WebStorm](https://www.jetbrains.com/help/webstorm/compiling-typescript-to-javascript.html#ts_compiler_compile_code_automatically) and [Visual Studio Code](https://code.visualstudio.com/docs/typescript/typescript-compiling#_step-2-run-the-typescript-build).
+   Refer to your IDE's guides to set this up. For instance, here are the guides for <a href="https://www.jetbrains.com/help/webstorm/compiling-typescript-to-javascript.html#ts_compiler_compile_code_automatically" target="_blank">WebStorm</a> and <a href="https://code.visualstudio.com/docs/typescript/typescript-compiling#_step-2-run-the-typescript-build" target="_blank">Visual Studio Code</a>.
 
 #### Editing frontend features
 

docs/userGuide/cliCommands.md

@@ -68,6 +68,8 @@ Usage: markbind <command>
 </div>
 <hr><!-- ========================================================================== -->
 
+<div id="serve-command">
+
 ### `serve` Command
 <br>
 
@@ -136,6 +138,7 @@ The caveat is that not building all pages during the initial process, or not reb
 * `markbind serve -p 8888 -s otherSite.json` : Serves the site in Port 8888 from the current working directory, using `otherSite.json` as the site configuration file.
 
 </panel>
+</div>
 
 <hr><!-- ========================================================================== -->
 

packages/core-web/src/styles/markbind.css

@@ -227,6 +227,10 @@ footer {
     color: white !important;
 }
 
+.mkb-text-violet {
+    color: violet !important;
+}
+
 /* Bootstrap small(sm) responsive breakpoint */
 @media (width <= 767.98px) {
     .dropdown-menu > li > a {

packages/core/src/lib/markdown-it/plugins/markdown-it-colour-text.js

@@ -36,6 +36,7 @@ module.exports = function colourtext_plugin(md) {
     [109, '#m#'],
     [121, '#y#'],
     [107, '#k#'],
+    [118, '#v#'],
     [119, '#w#'],
   ]);
   const delimMarkerToClassMap = new Map([
@@ -46,6 +47,7 @@ module.exports = function colourtext_plugin(md) {
     ['#m#', 'mkb-text-magenta'],
     ['#y#', 'mkb-text-yellow'],
     ['#k#', 'mkb-text-black'],
+    ['#v#', 'mkb-text-violet'],
     ['#w#', 'mkb-text-white'],
   ]);
 
@@ -59,7 +61,7 @@ module.exports = function colourtext_plugin(md) {
 
     if (marker === 35/* # */ &&
       acsiiCodeToTokenMap.has(state.src.charCodeAt(start + 1)) &&
-      start + 2 <= max && 
+      start + 2 <= max &&
       state.src.charCodeAt(start + 2) === 35/* # */
       ) {
       state.scanDelims(state.pos, true);