GitHub Community
-
|
I’m trying to make an ordered list of fenced code blocks and text items. I use
This shows correctly in GitHub’s markdown rendering, but the HTML generated starts each of the three items on this list with a 1. Earlier in this same document, the ordered lists work just fine with text and table items. Is there any way to place fenced code blocks on an ordered list? |
Beta Was this translation helpful? Give feedback.
Replies: 8 comments
-
|
rgplantz:
If you could paste the generated markdown (verbatim) it would be helpful. Once the problem is spotted in the markup, you should be able to easily fix your gen-code accordingly.
rgplantz:
Yes. Here’s the markdown (GFM) source: and here’s how it’s rendered:
|
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
This seems correct markdown code, but results might vary depending on the actual HTML renderer/engine used — the empty line between the two list elements is what might break their numeral sequence in HTML: some renderers require the empty line, others will treat it as an indication of a new list. GitHub uses its own markdown flavor (GFM), but its HTML rendering rules vary slightly in the context of repository documentation previews and Issues/Discussions, and other thread-based services. You should consult the Common Mark spec to ensure you’re abiding to it in your generated markdown: but also need to check the rendering engine used — and, if your markdown code is going to be used across different engines, you might need to adapt it to cover their needs via some options. Which renderer are you using to generate the final HTML doc? |
Beta Was this translation helpful? Give feedback.
-
|
I’m not the original poster. Just offering something that should work. Although I suppose I should have verified it in github.com instead of github.community. |
Beta Was this translation helpful? Give feedback.
-
|
Well, this is very embarrassing. I was not indenting the items (fenced code) in the list. When I followed the rules, it all worked as it should. Thank you tajmone and jsoref for taking the time to help me, and I apologize for not being more careful before asking. I’m a retired computer science professor, so I suppose this is some sort of karma. Please don’t tell any of my ex-students. :slight_smile: |
Beta Was this translation helpful? Give feedback.
-
|
rgplantz:
In principle that was correct, since markdown allows “lazy” formatting. The problem is that many non-Common Mark compliant parsers tend to be permissive about lazy formatting, which is positive on the one hand, but it has also been the root cause of discrepancies in behavior across different renderers. The Common Mark spec was the result of many years of discussions on the problems of markdown inconsistencies, and it was introduced to allow markdown parsers and renderers to move toward a unified syntax. As you can see, the section on lists is rather long to read. Although the basic rules are few, the Spec covers all edge cases and context that might affect lists. The markdown syntax remain simple to learn and use, but it was tweaked slightly to ensure rules and results consistency across different contexts. Some subtle aspects are rather trick, e.g. like list elements indentation being affected by the width of the list marker — exact indentation size has always been a major cause of cross-renders problems, some parsers expecting 2 spaces, other 3, and others even 4, not to mention tabs being interpreted differently from one library to another. When I need to work with markdown code generators that need to target different markdown engines, I usually rely on pandoc — i.e. I generated either pandoc’s markdown flavor or a pandoc document AST (JSON), and let pandoc convert it to desired markdown engine. Pandoc supports multiple markdown flavors, both as input and output formats:
and by tweaking various options and enabling/disabling extensions, you can mimic almost any markdown engine. So pandoc is definitely the tool to go when generating markup aimed at multiple rendering engines, with the added benefit that if you generate your document as a pandoc AST, you’re not limited to markdown either, but can also target al the other tons of lightweight markup syntaxes covered by pandoc, and many other documents formats. |
Beta Was this translation helpful? Give feedback.
-
|
Thank you very much for your help, Tristano. Your comments helped to inspire me to install pandoc on my Windows machine (where I’m doing much of the writing for my book) and learn a lot more about using it. In particular, I learned from the documentation (when in doubt, read the manual) that I need to convert from gfm, not markdown, to get good results. Wish I would’ve done this long ago. Very helpful! |
Beta Was this translation helpful? Give feedback.
-
|
Glad it helped. You might also look into PP, a pandoc-preprocessor which extends pandoc by allowing both built-in and custom macros. In this project of mine (a bit old) you’ll find and introduction to PP and some sample macros: tajmone/pandoc-goodiesA tresure-box of resources for pandoc, pp and Texts word processor. |
Beta Was this translation helpful? Give feedback.
In principle that was correct, since markdown allows “lazy” formatting. The problem is that many non-Common Mark compliant parsers tend to be permissive about lazy formatting, which is positive on the one hand, but it has also been the root cause of discrepancies in behavior across different renderers.
The Common Mark spec was the result of many years of discussions on the problems of markdown inconsistencies, and it was introduced to allow markdown parsers and renderers to move toward a unified syntax.
As you can see, the section on lists is rather long to read. Although the basic rule…