starred/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-26 01:36:03 +03:00
Code Issues 161 Projects Releases Packages Wiki Activity

[GH-ISSUE #1793] MD029: how to not trigger error when images are inserted between steps? Indentation insufficient. #745

New issue
Closed
opened 2026-03-03 01:29:32 +03:00 by kerem · 10 comments
kerem commented 2026-03-03 01:29:32 +03:00
Owner
Copy link

Originally created by @rlpitts on GitHub (Oct 3, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1793

I've been writing documentation for courses, and keep getting errors about MD029 of the form
Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/2/3]
when I embed images between steps in a numbered list. I thought embedding images between numbered list items would work like it does for code blocks, so I've tried aligning the indentation to match the first character of each numbered list item and made sure that there are blank lines around each image embed command, but the error messages are unchanged. Is MD029 just not designed to work around images? Or what am I missing?

If images between numbered list items aren't supported, may I request that as a feature?

Originally created by @rlpitts on GitHub (Oct 3, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1793 I've been writing documentation for courses, and keep getting errors about MD029 of the form `Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/2/3]` when I embed images between steps in a numbered list. I thought embedding images between numbered list items would work like it does for code blocks, so I've tried aligning the indentation to match the first character of each numbered list item and made sure that there are blank lines around each image embed command, but the error messages are unchanged. Is MD029 just not designed to work around images? Or what am I missing? If images between numbered list items aren't supported, may I request that as a feature?
kerem 2026-03-03 01:29:32 +03:00
  • closed this issue
  • added the
    question
         label
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@DavidAnson commented on GitHub (Oct 3, 2025):

Not sure what you mean - I've done what you describe here with no violations reported:

https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0A1.%20Item%0A%20%20%20!%5BImage%5D(image.png)%0A2.%20Item%0A

<!-- gh-comment-id:3365731983 --> @DavidAnson commented on GitHub (Oct 3, 2025): Not sure what you mean - I've done what you describe here with no violations reported: https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0A1.%20Item%0A%20%20%20!%5BImage%5D(image.png)%0A2.%20Item%0A
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@rlpitts commented on GitHub (Oct 3, 2025):

Oh, does that mean including blank lines around the images actually throws it off? So it's different from code?
I mean, the page renders OK, but it raises markdown errors.

<!-- gh-comment-id:3365736346 --> @rlpitts commented on GitHub (Oct 3, 2025): Oh, does that mean including blank lines around the images actually throws it off? So it's different from code? I mean, the page renders OK, but it raises markdown errors.
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@DavidAnson commented on GitHub (Oct 3, 2025):

Also no violations:

https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0A1.%20Item%0A%0A%20%20%20!%5BImage%5D(image.png)%0A%0A2.%20Item%0A

<!-- gh-comment-id:3365738781 --> @DavidAnson commented on GitHub (Oct 3, 2025): Also no violations: https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0A1.%20Item%0A%0A%20%20%20!%5BImage%5D(image.png)%0A%0A2.%20Item%0A
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@rlpitts commented on GitHub (Oct 3, 2025):

In that case, I wonder if it's an issue of including these features inside tabs.

<!-- gh-comment-id:3365741768 --> @rlpitts commented on GitHub (Oct 3, 2025): In that case, I wonder if it's an issue of including these features inside tabs.
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@DavidAnson commented on GitHub (Oct 3, 2025):

If you show an example, I can explain what's happening.

<!-- gh-comment-id:3365853595 --> @DavidAnson commented on GitHub (Oct 3, 2025): If you show an example, I can explain what's happening.
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@rlpitts commented on GitHub (Oct 6, 2025):

Here's an example tab:

=== "Kebnekaise"

    To start an Open OnDemand session on Kebnekaise,
    
    1. Open [https://portal.hpc2n.umu.se](https://portal.hpc2n.umu.se) in your browser. The page looks like this:
    
        <img src="https://docs.hpc2n.umu.se/images/open-ondemand-portal.png" alt="HPC2N Open On-Demand Portal" width="1200"/>
    
    2. Click the blue button labeled "Login to HPC2N OnDemand".
    3. A login window should open with boxes for your login credentials. Enter your HPC2N username and password, then click "Sign In".
    4. You will now be on the HPC2N Open OnDemand dashboard. The top of it looks like this:
    
        <img src="https://docs.hpc2n.umu.se/images/open-ondemand-dashboard.png" alt="HPC2N Open On-Demand Portal" width="1200"/>
    
    5. Find the `Interactive Apps` tab in the menu bar along the top and click it to open a drop-down menu of available apps. The menu currently looks like this:
    
        <img src="https://docs.hpc2n.umu.se/images/open-ondemand-apps.png" alt="HPC2N Open On-Demand dashboard" width="1200"/>
<!-- gh-comment-id:3371289502 --> @rlpitts commented on GitHub (Oct 6, 2025): Here's an example tab: ``` === "Kebnekaise" To start an Open OnDemand session on Kebnekaise, 1. Open [https://portal.hpc2n.umu.se](https://portal.hpc2n.umu.se) in your browser. The page looks like this: <img src="https://docs.hpc2n.umu.se/images/open-ondemand-portal.png" alt="HPC2N Open On-Demand Portal" width="1200"/> 2. Click the blue button labeled "Login to HPC2N OnDemand". 3. A login window should open with boxes for your login credentials. Enter your HPC2N username and password, then click "Sign In". 4. You will now be on the HPC2N Open OnDemand dashboard. The top of it looks like this: <img src="https://docs.hpc2n.umu.se/images/open-ondemand-dashboard.png" alt="HPC2N Open On-Demand Portal" width="1200"/> 5. Find the `Interactive Apps` tab in the menu bar along the top and click it to open a drop-down menu of available apps. The menu currently looks like this: <img src="https://docs.hpc2n.umu.se/images/open-ondemand-apps.png" alt="HPC2N Open On-Demand dashboard" width="1200"/> ```
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@DavidAnson commented on GitHub (Oct 6, 2025):

Your example produces no warnings as is:

https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0A%3D%3D%3D%20%22Kebnekaise%22%0A%0A%20%20%20%20To%20start%20an%20Open%20OnDemand%20session%20on%20Kebnekaise%2C%0A%20%20%20%20%0A%20%20%20%201.%20Open%20%5Bhttps%3A%2F%2Fportal.hpc2n.umu.se%5D(https%3A%2F%2Fportal.hpc2n.umu.se)%20in%20your%20browser.%20The%20page%20looks%20like%20this%3A%0A%20%20%20%20%0A%20%20%20%20%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-portal.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20Portal%22%20width%3D%221200%22%2F%3E%0A%20%20%20%20%0A%20%20%20%202.%20Click%20the%20blue%20button%20labeled%20%22Login%20to%20HPC2N%20OnDemand%22.%0A%20%20%20%203.%20A%20login%20window%20should%20open%20with%20boxes%20for%20your%20login%20credentials.%20Enter%20your%20HPC2N%20username%20and%20password%2C%20then%20click%20%22Sign%20In%22.%0A%20%20%20%204.%20You%20will%20now%20be%20on%20the%20HPC2N%20Open%20OnDemand%20dashboard.%20The%20top%20of%20it%20looks%20like%20this%3A%0A%20%20%20%20%0A%20%20%20%20%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-dashboard.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20Portal%22%20width%3D%221200%22%2F%3E%0A%20%20%20%20%0A%20%20%20%205.%20Find%20the%20%60Interactive%20Apps%60%20tab%20in%20the%20menu%20bar%20along%20the%20top%20and%20click%20it%20to%20open%20a%20drop-down%20menu%20of%20available%20apps.%20The%20menu%20currently%20looks%20like%20this%3A%0A%20%20%20%20%0A%20%20%20%20%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-apps.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20dashboard%22%20width%3D%221200%22%2F%3E%0A

However, because the syntax you use for tabs is not part of the CommonMark specification, the four-space indent style causes everything to be treated as a code block.

I extracted the relevant part of the body of your example and we see that no MD029 violations are reported with the placement of an HTML image between two Markdown list items:

https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0ATo%20start%20an%20Open%20OnDemand%20session%20on%20Kebnekaise%2C%0A%0A1.%20Open%20%5Bhttps%3A%2F%2Fportal.hpc2n.umu.se%5D(https%3A%2F%2Fportal.hpc2n.umu.se)%20in%20your%20browser.%20The%20page%20looks%20like%20this%3A%0A%0A%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-portal.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20Portal%22%20width%3D%221200%22%2F%3E%0A%0A2.%20Click%20the%20blue%20button%20labeled%20%22Login%20to%20HPC2N%20OnDemand%22.%0A

<!-- gh-comment-id:3371451485 --> @DavidAnson commented on GitHub (Oct 6, 2025): Your example produces no warnings as is: https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0A%3D%3D%3D%20%22Kebnekaise%22%0A%0A%20%20%20%20To%20start%20an%20Open%20OnDemand%20session%20on%20Kebnekaise%2C%0A%20%20%20%20%0A%20%20%20%201.%20Open%20%5Bhttps%3A%2F%2Fportal.hpc2n.umu.se%5D(https%3A%2F%2Fportal.hpc2n.umu.se)%20in%20your%20browser.%20The%20page%20looks%20like%20this%3A%0A%20%20%20%20%0A%20%20%20%20%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-portal.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20Portal%22%20width%3D%221200%22%2F%3E%0A%20%20%20%20%0A%20%20%20%202.%20Click%20the%20blue%20button%20labeled%20%22Login%20to%20HPC2N%20OnDemand%22.%0A%20%20%20%203.%20A%20login%20window%20should%20open%20with%20boxes%20for%20your%20login%20credentials.%20Enter%20your%20HPC2N%20username%20and%20password%2C%20then%20click%20%22Sign%20In%22.%0A%20%20%20%204.%20You%20will%20now%20be%20on%20the%20HPC2N%20Open%20OnDemand%20dashboard.%20The%20top%20of%20it%20looks%20like%20this%3A%0A%20%20%20%20%0A%20%20%20%20%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-dashboard.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20Portal%22%20width%3D%221200%22%2F%3E%0A%20%20%20%20%0A%20%20%20%205.%20Find%20the%20%60Interactive%20Apps%60%20tab%20in%20the%20menu%20bar%20along%20the%20top%20and%20click%20it%20to%20open%20a%20drop-down%20menu%20of%20available%20apps.%20The%20menu%20currently%20looks%20like%20this%3A%0A%20%20%20%20%0A%20%20%20%20%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-apps.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20dashboard%22%20width%3D%221200%22%2F%3E%0A However, because the syntax you use for tabs is not part of the CommonMark specification, the four-space indent style causes everything to be treated as a code block. I extracted the relevant part of the body of your example and we see that no MD029 violations are reported with the placement of an HTML image between two Markdown list items: https://dlaa.me/markdownlint/#%25m%23%20Issue%201793%0A%0ATo%20start%20an%20Open%20OnDemand%20session%20on%20Kebnekaise%2C%0A%0A1.%20Open%20%5Bhttps%3A%2F%2Fportal.hpc2n.umu.se%5D(https%3A%2F%2Fportal.hpc2n.umu.se)%20in%20your%20browser.%20The%20page%20looks%20like%20this%3A%0A%0A%20%20%20%20%3Cimg%20src%3D%22https%3A%2F%2Fdocs.hpc2n.umu.se%2Fimages%2Fopen-ondemand-portal.png%22%20alt%3D%22HPC2N%20Open%20On-Demand%20Portal%22%20width%3D%221200%22%2F%3E%0A%0A2.%20Click%20the%20blue%20button%20labeled%20%22Login%20to%20HPC2N%20OnDemand%22.%0A
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@rlpitts commented on GitHub (Oct 6, 2025):

OK, maybe I need to find a different code block.

The tab width varies from file to file, and the web interface is kind of flaky both in its response to changing the tab size settings and whether or not it adjusts the indentation plus or minus a space to match the level nesting.

I guess the lesson is to work locally instead of in the web interface?

Also, what is CommonMark specification? What is the proper tab syntax, then?

<!-- gh-comment-id:3371561014 --> @rlpitts commented on GitHub (Oct 6, 2025): OK, maybe I need to find a different code block. The tab width varies from file to file, and the web interface is kind of flaky both in its response to changing the tab size settings and whether or not it adjusts the indentation plus or minus a space to match the level nesting. I guess the lesson is to work locally instead of in the web interface? Also, what is CommonMark specification? What is the proper tab syntax, then?
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@DavidAnson commented on GitHub (Oct 6, 2025):

https://spec.commonmark.org/0.31.2/

<!-- gh-comment-id:3372901505 --> @DavidAnson commented on GitHub (Oct 6, 2025): https://spec.commonmark.org/0.31.2/
kerem commented 2026-03-03 01:29:33 +03:00
Author
Owner
Copy link

@rlpitts commented on GitHub (Oct 7, 2025):

Thank you

Well, the website looks fine, so I'm going to close this issue.

<!-- gh-comment-id:3376031440 --> @rlpitts commented on GitHub (Oct 7, 2025): Thank you Well, the website looks fine, so I'm going to close this issue.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
next
linkinator-action@v2.4.1
linkinator-action@v2.4.0
wc13
scenario-chunks
seqseq
v0.40.0
v0.39.0
v0.38.0
v0.37.4
v0.37.3
v0.37.2
v0.37.1
v0.37.0
v0.36.1
v0.36.0
v0.35.0
v0.34.0
v0.33.0
v0.32.1
v0.32.0
v0.31.1
v0.31.0
v0.30.0
v0.29.0
v0.28.2
v0.28.1
v0.28.0
v0.27.0
v0.26.2
v0.26.1
v0.26.0
v0.25.1
v0.25.0
v0.24.0
v0.23.1
v0.23.0
v0.22.0
v0.21.1
v0.21.0
v0.20.4
v0.20.3
v0.20.2
v0.20.1
v0.20.0
v0.19.0
v0.18.0
v0.17.2
v0.17.1
v0.17.0
v0.16.0
v0.15.0
v0.14.2
v0.14.1
v0.14.0
v0.13.0
v0.12.0
v0.11.0
v0.10.0
v0.9.0
v0.8.1
v0.8.0
v0.7.0
v0.6.4
v0.6.3
v0.6.2
v0.6.1
v0.6.0
v0.5.0
v0.4.1
v0.4.0
v0.3.1
v0.3.0
v0.2.0
v0.1.1
v0.1.0
v0.0.8
v0.0.7
v0.0.6
v0.0.5
v0.0.4
v0.0.3
v0.0.2
v0.0.1
Labels
Clear labels   
bug

   
enhancement

   
enhancement

   
enhancement

   
fixed in next

   
fixed in next

   
fixed in next

   
new rule

   
new rule

   
new rule

   
pull-request

Mirrored from GitHub Pull Request

  
question

   
refactoring

   
refactoring
No labels
bug
enhancement
enhancement
enhancement
fixed in next
fixed in next
fixed in next
new rule
new rule
new rule
pull-request
question
refactoring
refactoring
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
starred/markdownlint#745
No description provided.