Bug: null error in lessons with magic comments for markdownlint

[Josh Smith]

Checks

• I have thoroughly read and understand The Odin Project Contributing Guide
• The title of this issue follows the Bug: brief description of bug format, e.g. Bug: Lesson complete button does not update on click
• Would you like to work on this issue?

Bug description

Since the introduction of markdownlint in the curriculum repo, some lessons have a comment at the top to disable or configure the linter in some way. An example can be seen with the setting up git lesson.

If you navigate to a lesson that has one of these lint comments, an error will crop up in the console from the LessonTocController (a Stimulus controller) attempting to work with the content for the comment.

How to reproduce

1. Navigate to a lesson with one of these comments. Setting up Git is a good example.
2. Look in the console and observe the error:
   

Even more noticeable with the project locally, as the error will be much more intrusive:

Expected behavior

1. Functions without JavaScript errors.

What browsers are you seeing the problem on?

Firefox, Chrome

What OS are you using?

Ubuntu

Discord Name

No response

Additional Comments

I'd be glad to work on fixing this. A couple of different avenues for a solution come to mind.

1. Adjust the LessonTocController to ignore the section containing the comment.
2. Adjust the logic with Kramdown such that these comments aren't included at all in the HTML document output by the parsing.

[Kevin]

Sorry I'm just getting to this now @JoshDevHub. Ignoring comments during the Kramdown parsing step sounds like the ideal way to me. But if thats overly difficult to do, adjusting the Lesson Toc controller would be a good way around it too.

Would you still like to be assigned? I appreciate its been a while since this was opened.

[Josh Smith]

Hey @KevinMulhern it's no big deal. I'd still be glad to work on this issue 😃

I'll try out fixing with Kramdown and see if I can make progress on that. Agree that'd be the best thing to do.

[Kevin]

Thanks @JoshDevHub 💪. Give me shout if I can be of any help

[Josh Smith]

@KevinMulhern Alright I have a way forward on this but it's through JavaScript 😆

In the lessons_toc_controller.js, we can just have something like this, which is a very simple change:

activeSection(entries) {
   // ...
   const tocItem = this.tocTarget.querySelector(`li a[href="#${id}"]`)?.parentElement; // safe navigate here

   if (!tocItem) return; // early return if no `tocItem`
    // ...
 }

I did try to work on things with Ruby, but couldn't get it to come together, and I suspect a change on that end will be more complicated. I originally thought that going to OdinHtml and just changing the conversion for comment would solve the problem:

module OdinHtml
  def convert_xml_comment(_element, _indent)
    ''
  end
end

But the parser still tries to section the content because of the newline characters that will still come out:

<!-- markdown comment -->\n
\n
<h3>Heading</h3>

Will become:

<section id="content>\n\n</section>

<section id="heading">
  <h3>Heading</h3>
</section>

Glad to investigate this more if you think it's worthwhile or know what to change for getting it to work on the Kramdown side of things.

[Kevin]

Thanks @JoshDevHub, that looks like a good simple fix to me.

Thanks for investigating the Kramdown route. It would be nice to strip out comments before converting. But this problem definitely seems better solved in the toc controller and your fix should make it more resilient to other changes we might introduce in the markdown later 💪