How to Correctly Create Markdown Files Containing Code Blocks

A bug has been reported where files are not correctly updated in Composer when Markdown contains code blocks. Here’s a way to work around this issue.

If you instruct:

“Please indent the code block.”

The indentation is present, but with this instruction, a Markdown file containing code blocks will be created.

2 Likes

Great, thanks for the information.

Thanks. I’ll add it to the system prompt :metal:t2:

@rizumita telling cursor to indent correctly gives a complete file but previewing with extensions like markdown preview does not give a correct preview. in markdown, code blocks should not be indented.

I am using the following system prompt for a readable preview.

- When proposing an edit to a markdown file, first decide if there will be code snippets in the markdown file.
- If there are no code snippets, wrap the beginning and end of your answer in backticks and markdown as the language.
- If there are code snippets, do not wrap the beginning and end of your answers inside backticks. Instead, output the markdown content as free text. You may use backticks for code snippets within the markdown content.

This gives me something like

Hope that cursor teams fixes this!

That prompt is good too. Thank you!

For indentation, it seems that instructing to use two spaces for indentation will result in correct rendering in the preview.

1 Like

This prompt is more verbose than necessary, but I have found it to be reliable:

I notice that you often have trouble emitting markdown that includes code blocks--or at least the client I am using can't render it properly.  I have learned a trick for proper rendering:

Markdown recipe:

1. Use triple backticks to start and end the outer markdown code block and specify markdown beside your triple backticks. (Use this to start your ____ markup)

2. For the inner code block (for any code examples within your ____ section)
     a. drop a line after any heading and before starting your code block
     b. Indent the code block with 4 spaces. 
     c. Use triple backticks to start and end the inner code block.
     d. Specify the language next to your triple backticks (e.g., javascript) for syntax highlighting. plan markup.)

It is essential that you follow this guidence if I am to be able to use your output.
1 Like

Thanks @jpshack-at-palomar

@jpshack-at-palomar I preferred your output more because I believe having the file in a copy-friendly format is better than using rendered Markdown. However, I think the indentation for code blocks should be consistently set to 2 spaces (even if it’s currently 0 or 4) to adhere to syntactically correct Markdown and avoid issues with edits.

With your prompt, although generating files from scratch works good, editing files seems to not edit the existing indentation and causing rendering errors

My test md file if you want to try out

## Test Instructions

some text

```python
print("Hello, World!")
```

some text

  ```javascript
  console.log("Hello, World!");
  ```

some text

    ```bash
    echo "Hello, World!"
    ```

Your existing prompt with 4 spaces

Your prompt with 2 spaces

Revised rule I use forcing always 2 spaces even in edits

- When proposing an edit to a markdown file, first decide if there will be code snippets in the markdown file.
- If there are no code snippets, wrap the beginning and end of your answer in backticks and markdown as the language.
- If there are code snippets, indent the code snippets with two spaces and the correct language for proper rendering. Indentations level 0 and 4 is not allowed.
- If a markdown code block is indented with any value other than 2 spaces, automatically fix it

End result

2 Likes

@gokcin Thanks for sharing this. My markdown linter hadn’t complained but I see now that one of the preview plugins I was using did not render correctly as you showed. Thanks again!

1 Like

No problem at all, it was quite annoying to figure this out and cover the edge-cases so glad to help someone who also tried a super custom prompt :smiley:

I tried many things like forcing 5 backticks with markdown for the outer block, trying to escape backtick, 0 indentation for the inner block, 4, indentation for the inner block but never 2 until @rizumita pointed that out. So thanks!

I’ve found a workaround to this issue as well. Just use the ‘Copy message’ button at the bottom of the response (not any of the inline ones, they will only copy that segment). This copies the raw markdown and can be pasted into the code. You’ll need to delete the AI ‘fluff’ at the beginning and end, but I’ve found this to be the easiest way for now. I don’t want to add custom prompts for this because I do it rarely, and too many prompts may reduce the quality of my responses globally.