exploringCodebase.md

{% set title = "Exploring Codebase" %} {{ title }}

title: "{{ title }}" layout: devGuide.md pageNav: default

{{ title }}

This page provides an overview of the MarkBind codebase and innovative methods to explore it as an onboarding developer.

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

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.

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.

{.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.

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 lazy reload-olazy reload-o option to speed up page building
• the -d developer option.

{
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Dev Docs",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "cwd": "${workspaceFolder}/docs",
            "program": "${workspaceFolder}/packages/cli/index.js",
            "args": ["serve", "-o", "-d"]
        }
    ]
}

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.

{
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "test",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "cwd": "${workspaceFolder}",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "test"]
        }
    ]
}

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.

{
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "test cli",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "cwd": "${workspaceFolder}/packages/cli",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "test"]
        }
    ]
}

You can add multiple configurations as needed in debugging, each with their own respective application entry points, runtime arguments, and environment variables.

{.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.

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.

{.ms-4}

To learn more about debugging with Visual Studio Code, refer here for a more extensive official guide on debugging in VS Code.

Tested on JetBrains IDEs version `2024.1.1` and above. 1. Navigate to `Run` > `Edit Configurations...`. 2. Click the `+` icon and select `Node.js`. 3. Set the `Working directory` to the root of the MarkBind test site. Set the `Working directory` to `markbind/docs` to experiment with the MarkBind documentation site. 4. Set the `File` to the **ABSOLUTE PATH** of `packages/cli/index.js`. 5. Set the `Application parameters` to `serve -d -o`. 6. Name the configuration and click `OK`. 7. Add breakpoints to the lines you want to inspect. 8. Select the configuration from the dropdown next to the "run" button and click the "debug" button to start tracing.

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