Docs-website: Migration of nested bullet list comes over as numbered list

[rhetoric101]

Description

The migration process seemed to do two things related to a bullet list nested in an ordered list:

• It converted the nested bullet list to a nested ordered list.
• The images beneath each of the former bullets don't have the same indentation.

Steps to reproduce

1. Go to https://docs-preview.newrelic.com/docs/integrations/open-source-telemetry-integrations/opentelemetry/view-your-opentelemetry-data-new-relic#explorer
2. Compare that nested list to the original in Drupal's step 2 here: https://docs.newrelic.com/docs/integrations/open-source-telemetry-integrations/opentelemetry/view-your-opentelemetry-data-new-relic#explorer
3. Observer the difference in the indentation of the images in the nested list.

Expected behavior

I expected step 2 in the ordered list to have nested bullets (not numbers) and I expected the images to be equally spaced from the left margin.

Additional context

Here's the markdown that's a problem:

To get started with the explorer:

1. Open [https://one.newrelic.com](https://one.newrelic.com), and go to **explorer**.
2. Using the filter bar at the top, narrow your searches:
   1. Limit results to OpenTelemetry entities with the following:

      ![Screen capture showing how to filter for OpenTelemetry.](./images/explorer_filter_1.png "explorer_filter_1.png")
   2. After the OpenTelemetry filter, you can add another filter for your service based on the `service.name` attributes you've used. For example, to find `CartService`:

      ![Screen capture showing how to add a secondary filter for OpenTelemetry in explorer.](./images/explorer_filter_2.png "explorer_filter_2.png")
3. Click the service you want to know more about, and if you need help understanding the data, see the explanations below.

Environment

I'm seeing this problem in your main preview site.

On my local site, the images are brok for some reason. By the way, I get a "Permission denied" when I run the following: ./gatsby info --clipboard on my local instance.

[austin-schaefer]

@jpvajda @zstix : Marking this as launch-blocker, at least for triage. If this is one doc then it's fine, but I'm worried that there's a deeper issue with the migration script that might be silently hosing many docs.

[jpvajda]

Thanks @austin-schaefer I tagged is as GA sustainment, if we can't get to it before GA it will be one of the first things we look at post GA.

[jerelmiller]

After looking into this a bit more, it appears these are both ordered lists (<ol>), which is preserved, but the type has been dropped during the migration.

@rhetoric101 do you know if this is the only case of this happening? If so, this might be best to just a be a manual cleanup item. If not, we can see about adjusting our migration script to ensure <ol type="a"> gets preserved so that these list items render with letters instead of numbers.

[jpvajda]

I've followed up with @rhetoric101 on our question

[rhetoric101]

@jerelmiller and @jpvajda, it turns out I was mistaken in my explanation. Indeed, these are two ordered lists with inline formatting to force the child list to use lower-case letters. So, I'm guessing these uses of inline formatting are pretty rare on the site, but I have no way to quantify that. I think I've done this inline formatting trick a few times to get around a gap in our CSS. Since it's so late in the game, I think we can just fix these manually after the migration (when we find them).

On a related note, did you see the different spacing of the images in the child ordered list?

[jerelmiller]

Update: i've dug into this a bit more and there are quite a few more instances of the ordered list with alpha. I do think we should do this before GA. I'll go ahead and work on an update to the migration script to be able to handle this so that we can properly preserve the list items. Thanks for catching this!

On a related note, did you see the different spacing of the images in the child ordered list?

I do see this as well. I'll file a separate issue for this so that we can track it independently.

[jerelmiller]

Logged in https://github.com/newrelic/docs-website/issues/945

[jerelmiller]

Ok so I've got some bad news. It turns out markdown doesn't really support list items as alpha (a, b, c, etc.), which means that trying to migrate this is tricky. I'm not sure exactly what's important here, but we have a couple options to consider:

1. Maintain ordered lists using the alphabet by using raw HTML

If the ordered list items using the alphabet is important, we'll need to use raw HTML (technically JSX) instead of markdown for this. While this might look nice to the end user, using HTML to build lists in markdown kind of defeats the purpose of using markdown to begin with. It seems many of the cases for alpha ordered lists are from nested list items. Here is a sample of what that might look like:

1. List item 1
  <ol type="a">
    <li>
      Nested list item 1
    </li>
    <li>
      Nested list item 2

      ```js
      const withACodeBlock = true
      ```
    </li>
  <ol>

You can see this gets pretty verbose very quickly.

1. Convert nested list items to unordered lists

In this case, we'd be able to continue to use markdown for the nested list items, but we lose the ordering. Depending on how important that ordering is, this may be a good option.

1. Leave it as-is

Right now its converting those ordered list items to numbers, so while the alpha ordering isn't being carried over, you still have an ordered list.

After researching this, I'd opt for option 3, personally. If the alpha ordering is merely a stylistic thing, I'm not sure you lose that much leaving it as numbers. That being said, I'm not sure exactly how important the alpha ordering is, so please let us know if this is important enough to carry over.

We'll want to make a decision on this pretty quickly as we'll want to make sure the migration script is updated with any updated behavior before our freeze.

[austin-schaefer]

I'd opt for leaving as-is, or converting them to unordered lists in Drupal. Alpha ordering seems like a pretty rare use case to me, and not one I'd like to stretch our markup to cover.

[jerelmiller]

@austin-schaefer if we go the unordered list route, no need to update in drupal. We can handle that on our end in the migration script.

@rhetoric101 I'll let you be the tie-breaker. Do you think this would work better as as-is, or should these cases get converted to an unordered list?

[roadlittledawn]

@jerelmiller curious if we would want to add style rule in theme / docs site for ol li ol li and specify the list-style-type. i suppose the one downside is the .mdx file list with all numerals would be different than what it gets rendered on front end (numerals for level 1, lower alpha for level 2).

[jerelmiller]

@roadlittledawn we could but I'd be hesitant to make that change because it may or may not work in all situations. When I initially updated the migration to try this out, there definitely were changes on little more than a handful of docs, but I'm sure there are also plenty of situations with nested ordered lists that aren't alpha as well.

[rhetoric101]

@jerelmiller, I think that option #3 sounds pretty safe: convert nested ordered lists from alpha to numeric. If we go this route, it might still be helpful to get a sense for how many docs are affected. Is it easy to generate run a query to tell us the docs that have this type of inline formatting?

[jpvajda]

So if we go with option 3, this sounds like a won't fix bug and we can close it? cc @rhetoric101 / @austin-schaefer - can you confirm

 3.   Leave it as-is

Right now its converting those ordered list items to numbers, so while the alpha ordering isn't being carried over, you still have an ordered list.

After researching this, I'd opt for option 3, personally. If the alpha ordering is merely a stylistic thing, I'm not sure you lose that much leaving it as numbers. That being said, I'm not sure exactly how important the alpha ordering is, so please let us know if this is important enough to carry over.

We'll want to make a decision on this pretty quickly as we'll want to make sure the migration script is updated with any updated behavior before our freeze.

[jerelmiller]

@jpvajda thats correct. I'll see what I can do to pull up a report on which of these lists are affected, but otherwise we don't need to do anything here.