Updating README.md I'm able to use a code fence. It produces a left justified code block with proper syntax highlighting.
However I'm unable to get the code fence to properly nest under a list. It will remain left justified and disrupt my ordered list. Using various combinations of spaces and tabs will at best include the code fence characters as part of the code block.
I can forego the code fence and use the space/tab technique for code but then I lose the syntax highlighting.
What's the best technique for achieving code syntax highlighting nested in a list?
Hello Paul and welcome to the Community!
I read through your post, and thank you for providing great amounts of detail, and attempting to recreate the issue within Bitbucket Cloud. From what I was able to recreate I am unsure if it is matching your desired output or not. Here is what I have done thus far:
I create the readme.md file and within then I added the following:
From this, the file is displayed as follows:
Is this similar to what you’re seeing as well? If not, can you please give us a sample of the readme.md file you’re using so we may test further with that to find the issue you’re seeing.
We look forward to your response so we may work together to resolve this issue.
Hi Stephen and thanks for the quick response! That's what I'm seeing except I have list items following the code fence. With the code being left justified, the numbering restarts for any list item after it.
Using tabs and spaces will at best make the code fence characters part of the code block causing syntax highlighting to be lost.
Hello again Paul,
Thank you for the response and clarification. Reviewing you’re follow up and testing, I did find what the issue may be. Within the markdown itself, it is escaping when you enter the code block itself, this is why the code block will not indent with the list. The list will also be escaped (Using your example) Item number 3 will display as number 1 after the code block. You may also tab the code within the code block to indent, but the list will still be escaped. Here are examples here:
There is more information about the markdown at Daring Fireball | Code Block. Within there they explain the following:
Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.
This would explain the behavior of the markdown being escaped in the middle of the list due to the code block.
I hope this helps to clarify how the markdown functions and give you an option to indent your code into your list.
This isn't an answer. This is an explanation of what is happening. If anything, you should explicitly say "No, we do not currently support syntax coloring for code blocks embedded in a list." You mention markdown syntax is not processed within code blocks but I believe that is obvious and is not related to what we are attempting to do.
I'm with Paul Hanson this is a desired capability. I am running into the same limitation. This syntax coloring via Pygments is a feature BitBucket has integrated into its display of Markdown which is fantastic but limited if you are not providing instructions with numbered steps.
If there is a way to continue the numbering of a list after a code block then that is desired. My use case: Writing installation instructions (ordered list) and would like to display a code block with colored syntax as 1 step. Restarting the list numbering after the codeblock is unacceptable.
I agree with the other commenters. Making markdown documentation hosted by bitbucket is an exercise in frustration. The answer should not have been accepted as it was an admission that there is a bug with the way markdown is processed. Code blocks should not break lists!
Edit: I have spent more time trying to get my code blocks to display in a list correctly than actually writing the documentation in the first place!
I have similar a problem, with code blocks not formatted properly if inside a list. Same markdown README is working as expected on Github. Example:
1. Starting a list
$ python -c "print('Hello world!')"
1. Next element of the list
Starting a list
$ python -c "print('Hello world!')"Hello world!
Next element of the list
As you can see, different lines from code block are concatenated, which is not happening on Github.
Oh wow, the amount of time I've spent on this thinking I did something wrong.
Yes please, we need this, too.
In the Readme file, we often have a list of steps, and some steps would have a code snippet or a command. There's currently no way to format that!
The closest I could find to an acceptable layout is using blockquotes, but we lose the highlighting (and we get annoying double-quotes at the beginning and end of the code). Not ideal!
Hi everyone, Are you Bitbucket DC customer? If so, we'd love to talk to you! Our team wants to dive deep to understand your long-term plans regarding Bitbucket DC and Atlassian Cloud. Do you plan...
Connect with like-minded Atlassian users at free events near you!Find an event
Connect with like-minded Atlassian users at free events near you!
Unfortunately there are no Community Events near you at the moment.Host an event
You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events