Giters

miyakogi / m2r

Markdown to reStructuredText converter

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Code Block Within Ordered List Doesn't Render Properly

GLMeece opened this issue · comments

commented

Summary

If you create an ordered list (1, 2, 3, etc.) and embed a code block within it, even if it renders properly for the vast majority of Markdown editors/previewers, m2R either doesn't translate/render the code block correctly, or the numbering starts over if you format the Markdown so that it will render the code block correctly.

Reference Examples

Here's an example of a Markdown snippet that has an ordered list which includes a code block within it:

1. Open a terminal
2. Change to your favorite directory (i.e. `cd /opt`)
3. Clone the repository

```bash 
git clone git@someaccount/somerepo.git
```

4. Do the next thing you do

Expected Rendering Below

This renders (via most Markdown previewers, etc.) to:

  1. Open a terminal
  2. Change to your favorite directory (i.e. cd /opt)
  3. Clone the repository
git clone git@someaccount/somerepo.git
  1. Do the next thing you do

The equivalent reStructuredText block which would achieve the same thing would be:

#. Open a terminal
#. Change to your favorite directory (i.e. `cd /opt`)
#. Clone the repository

    .. code-block:: bash

      git clone git@someaccount/somerepo.git

#. Do the next thing you do

I've verified with Sphinx that the above does render the above code block pretty much as the section I've marked as Expected Rendering Below.

So - I know that it's possible to have an inline code block within an ordered list.

Issues

One is faced with a devil's dilemma - either have the code block rendered correctly and break the list "chain" and start a new ordinal sequence, or keep the ordinal chain sequence and have the code block not render correctly.

Approach 1 - Keep Order, Lose Code Block Rendering

If you format your Markdown as shown below, you'll keep your ordering...

1. Open a terminal
2. Change to your favorite directory (i.e. `cd /opt`)
3. Clone the repository
```bash 
git clone git@someaccount/somerepo.git
```
4. Do the next thing you do

...but it gets rendered like this (notice the `` .. code-block:: bash` at the end of line 3):

  1. Open a terminal
  2. Change to your favorite directory (i.e. cd /opt)
  3. Clone the repository .. code-block:: bash
git clone git@someaccount/somerepo.git
  1. Do the next thing you do

Approach 2 - Lose Order, Gain Code Block Rendering

If you have a Markdown snippet as seen above in Reference Examples, you'll get a rendering like this:

  1. Open a terminal
  2. Change to your favorite directory (i.e. cd /opt)
  3. Clone the repository
git clone git@someaccount/somerepo.git
  1. Do the next thing you do

Conclusion

I cannot find a reasonable compromise between maintaining an ordinal list and having a code block within it render properly. I'm forced to choose between a properly-rendered code block or a properly ordered list.

Note that I can provide screen shots and extra examples as needed.

commented

I found a very crude/non-optimal workaround. If you format your Markdown code thusly:

1) Open a terminal

2) Change to your favorite directory (i.e. `cd /opt`)

3) Clone the repository

```bash 
git clone git@someaccount/somerepo.git
```

4) Do the next thing you do

With Sphinx will render as:

  1. Open a terminal
  2. Change to your favorite directory (i.e. cd /opt)
  3. Clone the repository 
    git clone git@someaccount/somerepo.git
  4. Do the next thing you do

However, within Markdown, it will render the numbering literally as above (i.e., 1), 2)), plus if a line is too long, since Markdown doesn't think that line is an actual ordered line-item, it won't align the wrapped portion typographically.

So - it's a workaround, but IMO it's not a compromise I'd prefer to make.