numbers not rendering on the website in some instances

[mhamwala]

Expected Behavior

1. first item
2. second item
3. third item

Actual Behavior

1. first item
1. second item
1. third item

Steps to Reproduce the Problem

Some numbered bullet points are not rendering on the website but are fine in the github docs, this is the first instance I have seen of this happening, take a look at this Hello world sample app - https://knative.dev/docs/serving/samples/hello-world/helloworld-csharp/index.html

Additional Info

Additional context
Add any other context about the problem here.

[mhamwala]

I think what might be happening is that it renders every block after a ```shell block like a new list hence the recurring 1's, I cloud be wrong.

[samodell]

Thank you for looking into this!

@RichieEscarez some more website rendering issues.

[mhamwala]

I started looking into this, a potential fix could be adding four spaces to indent content between bullet points but I haven't figured out how to confirm that this works by viewing the rendered website.

having the same issue as: #1239

[RichieEscarez]

Looks like the Hugo markdown processor wants another single space added in front of any content in a nested list (that includes a line break).

Here is my test commit

which fixes the first bullet in the example topic reference in this issue: https://knative.dev/docs/serving/samples/hello-world/helloworld-csharp/index.html

[mhamwala]

Ahh I see, great @RichieEscarez , is this something that we should document or is it possible to change the rules for the Hugo markdown processor?

[RichieEscarez]

is this something that we should document or is it possible to change the rules for the Hugo markdown processor?

Looks like this has been a known Blackfriday issue for some time and the extra spacing that I found to fix our issue is what has been the "workaround".

Ill keep an eye out for alternate solutions and will try to document this soon. But even with a set of instructions in our repo it is un-intuitive to indent with "3-4 spaces" (especially if you use the "TAB" button). As far as our library, Ive seen some .md files where the author has either failed to indent all together, while some are indented normally ("1 tab"), and in both cases, its not obvious that there will be an rendering issue on knative.dev, given that the GitHub WYSIWIG renders correctly (and doesnt indicate any type of problem).

Render Test: "tabs vs spaces"
(where any nested content includes additional indentation)

Example using 4 spaces:

1. list

   1. nested (4 spaces)

      code here (8 spaces)
      

      1. nested (8 spaces)

         code here (12 spaces)
         

      2. nested (8 spaces)

Example using 1 tab:

1. list

   1. nested (1 tab)

      code here (2 tabs)
      

      1. nested (2 tabs)

         code here (3 tabs)
         

      2. nested (2 tabs)

Example with 3 spaces:

1. list

   1. nested (3 spaces)

      code here(6 spaces)
      

      1. nested (6 spaces)

         code here (9 spaces)
         

      2. nested (6 spaces)

If single tabs are used or if code blocks exclude additional indentation, lists break and the count restarts. When rendered on knative.dev it is more obvious and sometimes no indentation shows (even though GitHub renders it indented).

For examples:

1. list (broken example w/o additional indentation for nested content)

   1. nested (1 tab)

      code here (2 tabs - good)
      

      1. nested (2 tabs - ok/good)

         code here (3 tabs - good)
         

      2. nested (2 tabs - ok/good)

      code here (2 tabs - bad)
      

      Example: (2 tab - bad)

      example code here (2 tabs - bad)
      

      1. nested (2 tabs -> BROKEN)

      code here (2 tabs - bad)
      

[RichieEscarez]

FYI: I'm testing out possibility of using our "sock puppet" that runs 'prettier' on all the markdown. We still would be faced with the lack of any type of UI or linter that enforces "4 spaces" (during authoring or PR review/merge) but having all tabs converted into spaces will reduce the overhead of manually adding 1-2 spaces to any existing "tabs".

[mhamwala]

Sounds good!