Issues with Lists

[JoelMTaylor]

This question is an extensions of my previous question on Secondary and Tertiary Lists.

I changed the format of my ordered and unordered lists to be with four spaces instead of a tab. However, that didn't fix the problem and I have run into others.

@geoffreymcgill, you may be the only one able to view the pages due to the files and pages being restricted to only individuals in the organisation. However, I will try to include images where possible.

Firstly, I have created over 100 pages and I am now starting to get an issue that is fine in many other pages (of all the pages that have the formatting, only two have issues). These pages are Media and Publication Consent and Student Withdrawl. Both of these pages may be experiencing an issue with the formatting because the list is mixed-style (ordered and unordered together).

1. Media and Publication Consent - found in edumate\Enrolments\Media Consent.md.
   • Code:
     
   • Published page:
     
   • Notes: just a few lines above, I have the same situation without issue.
2. Student Withdrawl - found in edumate\Enrolments\Student\Student.md.
   • Code:
     
   • Published page:
     
   • Notes: again, there are no issues above, in a different click guide.

I had to convert several documents from Word (*.docx) to markdown. I experienced issues attempting to replicate the formatting of the Word document. In particular, the Word document included many ordered and unordered lists separated by line breaks, alerts and images. The converted markdown pages can be found in the folder Ci Anywhere and their respective GitHub pages. In particular, I would draw your attention to Disburse Purchase Card Expenses. As you will see from the code, the structure is a little messy with no clear and simply ordered structure. Of the nineteen steps, there is no issue until the tenth. At this point, the similar structure that has occurred earlier suddenly breaks down and it gets confused.

3. Disburse Purchase Card Expenses - found in ci-anywhere\Disburse-purchase.md.
   • Code:
     
   • Published page:
     
   • Notes: I was surprised that following the structure of the indent worked. I don't know why it would break there or how to fix it (I did may tests including line breaks (<br>) to maintain the structure (which was moderately successful).
   • Other pages: I also experienced these issues in Submit a Purchase Requisition from step 11; and Approve Purchase Card Disbursements from step 4c.

I experienced some odd issues with inconsistent paragraph spacing between the primary ordered list (1,2,3).

4. The Account String - found at ci-anywhere\Account-String.md
   • Code: each new section of the ordered list has the same consistent formatting
   • Published page: but the eighth point has a smaller/no paragraph space above (between 7d and 8)
   • Other pages: Approve a Purchase Requisition has small/no paragraph spacing above (spacing is present due to the image in line); Approve Purchase Card Disbursements appears to start off with spacing before it stops from step 3; Disburse Purchase Card Expenses maintains consistent large paragraph spacing between each primary ordered list, but has a hiccup between 5d and 5e (probably due to a kind of line break - which is supposed to maintain the same in indentation but without a ordered number at the start); Submit a Purchase Requisition from step 13 reverts to small/no paragraph spacing; and Transmit or Amend a Purchase Order from step 2.

Similar to maintaining the ordered structure (point three), I had issues inserting an image at the same indent of a sub-point and maintaining the same indent or structure as required.
5. Approve a Purchase Requisition - found at ci-anywhere\Approve.md.
- Code:

- Published page:

- Notes: this occurs for any image at a second or tertiary level (not at the primary/no level) and that I am trying to achieve the same as is occurring with the images after 'code' or 'published pages'.
- Other pages: Receive Goods or Service from a Purchase Order; and Transmit or Amend a Purchase Order.

That is a lot of information. I know that Markdown is going to be different to Word and where formatting cannot be completed the same I will just have to life with or work around. However, I just want to ask and check first - because there have been many times where I was unaware of an issue or solution (such as the duplicate document 'idea').

Thank you again for all your assistance.

[geoffreymcgill]

Hi @JoelMTaylor,

I tried the source for Disburse-purchase.md in the CommonMark playground and the formatting began failing around item 10 as well. I noticed that you had an extra space in front of each list item. Once I remove that extra space char, the formatting appears to work as expected.

I'll have to read through the CommonMark spec to figure out the exactly why a single digit list marker with a leading space works, but a double-digit list marker with a leading space fails.

Removing those extra leading spaces should solve the formatting issues. I will do some research too.

[JoelMTaylor]

I noticed that you had an extra space in front of each list item. Once I remove that extra space char, the formatting appears to work as expected.

Thanks @geoffreymcgill for the advice. Removing the space at the front of the ordered list at the primary level fixed the issues with (1), (2) and (3).

[JoelMTaylor]

I have been playing around again, trying to find a solution that appears fine. I tried to test things with the CommonMark Playground, but found that it did not display things consistently to Retype (some for better, others for worse).

Item 4 was of particular annoyance to me since I am inclined to noticing and having issue with even very minor inconsistencies. I tried various solutions, but each required some use of <br> in order to hack a solution.

Before I explain what I have tested, I want to mention that I have defined a few terms at the bottom of this post to ensure that nothing of this explanation is lost. Review this if you wish. If I have any of these terms incorrect, please let me know.

The consistent pattern of ordered, unordered and mixed lists seems to be one with no paragraph spacing between individual items. That is, there is no gap between 1,2,3 or 1,a,b,2. Each appears close. For example:

However, this could be changed by entering one extra line break in one location. By doing so, each list item has paragraph spacing.

While I don't know why this happens (I haven't read through the CommonMark documentation enough), this seems to be a pleasing option and could be used as required. In my directionless testing, I can confirm this to be true for me - in the most part. There is one issue which seems to be at the root of my question above (point three).

It seems to me that there is an issue with how the paragraph spacing is created when an additional line break is added at a list item (example two just above). In the code excerpt below, one would presume that the paragraph spacing would mimic that of the line breaks. However, this is not what occurs.

• page: Account String - found at ci-anywhere\Account-String.md
• code:
  
• published page:
  

I consistently find that when a primary ordered list item (e.g. 1,2,3; I have not tested with unordered lists) is preceded by secondary ordered list item (e.g. a,b,c), that primary item fails to have the correct paragraph spacing. The only solution that I could hack was to have two breaks in order to force the appearance of the correct paragraph spacing (one break would not be sufficient). As you can probably guess, extra line breaks was not successful (only two breaks).

If creating lists with a small amount of paragraph spacing is built in to CommonMark (according to example two), then I suppose this is an issue to be fixed.

Similarly, I noticed a behaviour with alerts within a list that did the opposite - added paragraph spacing after when none was expected. When using on single break spacing (tight list like example one), an alert adds the paragraph space succeeding itself, regardless of the context (that is, indent level).

• page: Approve a Purchase Requisition - found at ci-anywhere\Approve.md.
• code:
  
• published page:
  

I suppose this also to be an issue. Also, one may notice that tabs are used instead of spaces for indents. I regularly switched between the two to make sure one or other was not the issue. I have not found an instance where spaces work and tabs do not. I would further add that I was not able to hack a fix for this as adding a break <br> at the end of the final !!! breaks (damages) the code.

So, while I was able to find a hack for displaying the list with extra paragraph spacing, I preferred the more consistent (to my other pages) single spacing. This provided me another issue to solve - point four of my main post above. The obvious answer would be to have an extra line break between the primary (or secondary) item and the image. However, doing so causes the paragraph spacing issue I am also trying to avoid. The hack that I found was to insert a break <br> at the end of the preceding line. This would have to be done for images and <mark> (edit: it is with images and indented text [without leading number/letter/symbol]). I initially thought that it would need to be done the line preceding and proceeding (at the end of the image line), but the later turned out to unnecessary.

• page: Receive Goods or Service from a Purchase Order - found at ci-anywhere\Receive.md.
• code:
  
• published page:
  

@geoffreymcgill, if you have any solutions or ideas, or you perceive any of these to be issues that you desire to fix (at any time in the future), please let me know.

While it would be nice to not require any hacks in order to achieve a desired appearance, it is plain to understand that Markdown is designed for simplicity and to be light and one cannot have it both ways. If a solution is to be found to added in the future, that would be great. Otherwise, we make it work or make do.

---

Definitions of terms:

1. A "break" refers to the use of <br>. Normally, this is done at the end of one line instead of entering two "line breaks".
2. A "line break" refers to pressing enter at the end of a line to create a new line below. Normally, to separate sections of text that are not linked together (distinct "paragraphs"), two line breaks (enter is pressed twice) to create a gab between the two sections. Line breaks do not have a symbol in Studio Code, but just increase the numbering of the line by one.
3. A "paragraph" refers to two sections of text that are separated in order to show their different (that is, not consistent or continuous) nature.
4. A "paragraph spacing" refers to the space between two paragraphs that visually demonstrate their distinction.

[geoffreymcgill]

Hi @JoelMTaylor,

Regarding the lists and spacing, the following thread discussing CommonMark Loose Lists vs Tight Lists should help provide some insight, see #67

Instead of adding <br> line breaks, in Markdown you can end a line with a \ to force a hard line break. The \ gets converted to a <br /> in the final generated HTML.

As well, the lineBreaks config might also be something you would like to experiment with. Try the following setting in your retype.yml:

markdown:
  lineBreaks: hard

Hope this helps.

[JoelMTaylor]

Hi @geoffreymcgill,

That is very useful - the links are most helpful. [lineBreaks has the wrong hyperlink - but it was easy to find.]

It is particularly interesting about Andrey Chechel's solution to creating a loose list after a single item: []().

Do you have any ideas for creating the correct spacing following an alert? I tried using a \, but it behaves similarly to a <br>. [A reminder of the situation below.]