Support custom icons for lists

[damithc]

Suggestion: provide a way to specify custom icons for bullet lists, so that authors can use this kind of styles for lists easily.

The feature can be quite powerful if we combine it with our strong support for icons.

If the above can be achieved, it can be extend to numbered lists, to allow users to choose which kind of numbering to use (e.g., A, B, C instead of 1, 2, 3)

However, I expect coming up with an convenient syntax will be challenging, not to mention the feasibility of the implementation of such a feature.

[ang-zeyu]

Is this a duplicate? #906

[damithc]

Is this a duplicate? #906

Related, but not exactly the same.

This one is about replacing the default bullet icon with something else.

#906 is a so-called 'media list' in which the icon is a more prominent object (e.g., a picture) and the text is side-by-side with that object (like a two-column table).

[ang-zeyu]

Don't see why not. Do you have any ideas on the syntax? (in consideration with #906 as well)

Both are very similar in implementation and usage so it's best if it is somewhat consistent with each other.

[damithc]

Do you have any ideas on the syntax?

Not easy. How about something along the following lines?

Regular list with custom icons:

<icon-list>
* {.icon=":fas-tick:"} first item
* second item
  * {.icon=":fas-x:" .class="text-danger"} third item
  * fourth item
</icon-list>

Media-list (same syntax):

<icon-list icon-size="3">
* {.icon=":fas-tick:"} first item description
* {.icon=":fas-x:"} second item description
* {.icon="images/house.png"} second item description
</icon-list>

i.e., Specify icon at the start of the item. Use the same item for the subsequent items of the same level, until a new icon is given use that icon for items, unless overridden by a different icon in the item itself.

[ang-zeyu]

@SPWwj we use this plugin too https://www.npmjs.com/package/markdown-it-attrs which may give you some ideas to make the syntax even more user friendly (or not) and easily.

[SPWwj]

To accommodate the media list #906, I propose the following syntax for the new icon list:

- Header 1 { icon=":icon-tick:" }

  Content 1

- Header 2
    
    Content 2 { icon="/image.png" }
    
  - Header 2.1
  
- Header 3

- Header 4 
   - Header 4.1 

   { icon="x.png" size="xs"}
  
{ icon="x.png" size="xs" media}

The overall configuration is placed at the end of the document, as suggested by @ang-zeyu in PR #2309.

An additional optional 'media' attribute is used to distinguish the standard list from the media list. In this configuration, the first list item should be used as a header, while the remaining lines serve as content.

Based on issue #1778, it is safe to use 'icon-tick' instead of ':icon-tick:' in order to eliminate confusion.

The benefits of this implementation are twofold.

• First, it completely obviates the necessity for HTML tags, simplifying the syntax.
• Second, it repurposes existing Markdown rules, meaning features like nested lists are supported by default. This results in an elegant, streamlined approach to managing content.

[damithc]

@SPWwj After removing extra whitespace, it will be like this:

- Header 1{icon=":fas-tick:"}
  Content 1
- Header 2
  Content 2{icon="/image.png"}
  - Header 2.1
- Header 3
- Header 4 
  - Header 4.1 
   {icon="x.png" size="xs"}
{icon="x.png" size="xs" media}

I can't imagine having a default icon for a media list. So, we can probably omit that.
I don't think we need to support nested media lists either.

So, a regular list will be like the following?

- item 1 line 1{icon=":fas-tick:"}
- item 2 line 1
  item 2 line 2{icon="/image.png"}
- item 3 line 1{icon=":fas-tick:"}
- item 4
  - item 4.1{icon=":fas-tick:"}
  - item 4.2
  {icon=":fas-x:"}
- item 5
{icon=":fas-x:" size="s"}

size is optional.

What do you think?

[SPWwj]

What do you think?

The revised version looks much cleaner, indeed.
I just realized the two-space after the content behaves like a line break (</br>).
For the default configuration {icon=":fas-x:" size="sx"}, we need a line break to comply with Markbind syntax so it gets captured by the 'ul' tag above. So, the syntax will be:

- ### Header 1 { icon=":icon-tick:" xx= "XS" }
  Content 1
- Header 2  
  Content 2 { icon="/image.png" }  
  - Header 2.1
- Header 3  
- Header 4  
  - Header 4.1  
  
  { icon="x.png" xx="xs"}  

{ icon="x.png" xx="xs"}

Given that we can use the "#" symbols along with the size parameter, it inherently supports media list by default.

[damithc]

For the default configuration {icon=":fas-x:" size="sx"}, we need a line break to comply with Markbind syntax so it gets captured by the 'ul' tag above. So, the syntax will be:

line break or blank line?

What happens in the following case? x.png is used for the inner list or the outer list or both?

- ### Header 1 {icon=":icon-tick:" size= "XS" }
  Content 1
- Header 2  
  Content 2 {icon="/image.png" }  
  - Header 2.1
- Header 3  
- Header 4  
  - Header 4.1  

{icon="x.png" size="xs"}

Given that we can use the "#" symbols along with the size parameter, it inherently supports media list by default.

That's good. It's nicer if we can do both with the same syntax.

[SPWwj]

line break or blank line?

It is a blank line.

What happens in the following case? x.png is used for the inner list or the outer list or both?

I would recommend implementing a single-tiered configuration.

- ### Header 1 {icon=":icon-tick:" size= "XS" }
  Content 1
- Header 2  
  Content 2
  - Header 2.1
- Header 3  
- Header 4  
  - Header 4.1  

{icon="x.png" size="xs"}

Same as:

- ### Header 1 {icon=":icon-tick:" size= "XS" }
  Content 1 
- Header 2 {icon="x.png" size="xs"}
  Content 2
  - Header 2.1
- Header 3 {icon="x.png" size="xs"}
- Header 4 {icon="x.png" size="xs"}
  - Header 4.1  

The icon should only be tag to the title, thus there is a typo the in previous syntax.
Thus, this is not right

- Header 2  
  Content 2 {icon="/image.png" } 

[damithc]

@SPWwj I see. Can you post here a draft of the full explanation of the syntax that will go into the UG? That way, we have the full picture of the end result. The draft will not be a waste as it can be ported to the UG in your PR.

[SPWwj]

Building on the current Markbind list:

* Primary Entry 1
  * Secondary Entry 1.1
  * Secondary Entry 1.2<br>
    Secondary Line
    * Secondary Entry 1.2.1
* Primary Entry 2
* Primary Entry 3

The refined syntax for an icon list (with element-level config):

- Category 1 {icon="fas fa-times" size="xs"}
- Category 2 {icon="fas fa-times" size="xs"}
- Category 3 {icon="fas fa-times" size="xs"}
- Category 4 {icon="fas fa-times" size="xs"}

Expected Output for Icon List (with element-level config):

The refined syntax for an icon list (with regional-level config):

- Category 1 
- Category 2 
- Category 3 
- Category 4 

{icon="fas fa-times" size="xs"}

Expected Output for Icon List (with regional-level config):

The refined syntax for a media list (with element-level config):

- ## category 1 {icon="/image.png" size= "lg"}

  content 1 line 1,
  content 1 line 1 continue
- ## category 2 {icon="/image.png" size = "lg"}

  content 2
  - ## category 2.1
- ## category 3 {icon="/image.png" size = "lg"}

  content 3 line 1</br>
  content 3 line 2
- ## category 4 {icon="/image.png" size = "lg"}
  - ### category 4.1

Expected Output for Media List (with element-level config):

The refined syntax for a media list (with regional-level config):

- ## category 1

  content 1 line 1
  content 1 line 2
- ## category 2

  content 2
  - ## category 2.1
- ## category 3

  content 3 line 1</br>
  content 3 line 2
- ## category 4
  - ### category 4.1

{icon="image.png" size="lg"}

Notes

Please note the crucial use of the blank line between the content. It adheres to the markdown-it-attrs specifications. Failing to include it will cause the header parameters to be improperly captured, as the entire header and content will be considered as a single text component.

In addition to this, remember that you can change the color of the icon by using classes within the {}. For example, {class="text-danger" icon="x.png" size="xs"} would make the icon red.

Also, keep in mind that the configuration at the bottom such as '{icon="x.png" size="xs"}' is optional. This functions as a regional-level configuration. Once declared, it applies to all its direct child elements. However, specific element-level configurations, such as - ## category 1 {icon="/image.png" size= "xs"}, will override the regional-level configuration.

Finally, let's explore a demonstration showcasing the interplay between regional and element-level configurations:

- first item1
- second item {icon="fas fa-exclamation" size="xs" class="text-warning"}
- third item
- fourth item {icon="fas fa-check" size="xs" class="text-success"}

{icon="fas fa-times" size="xs" class="text-danger"}