Implement advanced lists (document lists)

[Reinmar]

Intro

The current implementation of lists assumes that a list item cannot contain any block content – that a list item is the lowest block element.

It means, that what the user sees as a "block" can either be a list item, paragraph or a heading. Never two at the same time.

It's a different model than what we had in CKEditor 4 where we allowed to have paragraphs and headings and other things in list items. The current CKEditor 5's implementation, which I call "article lists" (we can think of a better name), is definitely more limited. Let's clarify the whys and why nots.

Justification

However, before I'll get to that I'd like to clarify that IMO the current implementation isn't temporal. Block elements support won't be ever added to it because, simply, the article and document lists are two separate features. If we'll ever work on the document lists (I guess we'll do), then the developer will have to enable that feature and we yet have to define whether both kinds of lists can coexist in one editor.

Why we decided to work on article lists first:

• Because the UX, mental model and implementation are simpler if you don't allow blocks inside list items. There's a wide range of issues in CKEditor 4 when it comes to blocks inside list items. E.g. initially, a list is created without <p>s inside, but you can insert <hX> inside an item using the format dropdown and when you'll remove that format you'll be left with a <li><p>...</p></li>. You can't remove that <p> then, you have inconsistent markup and inconsistent styling (paragraphs usually have margins). And this is only one out of many, many issues (pasting, enter, and stability).
• Lists are lists and (at least IMO) should rather not be used to format big chunks of multiline, multi-format content. At least not in articles. See also @wwalc's https://github.com/ckeditor/ckeditor5-heading/issues/68#issuecomment-288243769.
• We're not alone in taking this direction. Medium and Draft.js editors also enforce such limitation.

Why we'll need to work on document lists:

• Often, you want to have multiline content in a list. I'm doing this very frequently myself with Markdown. It lets you better present a complex content. It's just useful if you used to do that.
• Actually, that was the only argument which came to my mind, but it's an important one. The more complex the content, the more need for more complex lists :).

Future

As I mentioned, I see document lists as a separate, opt-in feature. When implementing them we'll need to think on many UX and implementation aspects

• Whether both types of lists can exist in one editor – how to manage which are which, conversion between them, inconsistent markup (e.g. on paste), etc.
• What kind of formatting should be available in list items. E.g., we may say that headings should not be allowed, but multiple paragraphs, code blocks, block quotes, etc. are fine.
• The Enter behaviour. Should it create new list item or new paragraph (the latter could e.g. be done on Shift+Enter).
• How to represent them in the model and how to share current lists code with the new feature. E.g. I hope that we could use the same converters but with a different schema and Enter, Backspace modifiers and different commands. However, the dangerous part is that in this model, the <listItem> can be nested which will mean something different than subsequent items with different indent value.

Anyway, I wanted to start this topic and write down my concerns because I expect that we'll be asked about our current approach. However, I wouldn't like to think too much on this because I'm sure I just touched the tip of the iceberg.

---

If you'd like this feature to be implemented, add 👍 to this post.

[Reinmar]

I found this historical issue about blocks in list items: ckeditor/ckeditor5-design#11

It explains a bit more what problems one could have when mixing list items with blocks.

[iainhallam]

Another use case might be for legal documents which need to be published on the web, such as constitutions, contracts, etc. They often have numbered paragraphs and numbers on the headings as well, so in many ways, apart from preamble and explanation, they are complex nested lists. Items often need to have the ability to show a sublist, then return to the text to finish the explanation. There's a good example here:

http://weagree.com/weblog/numbering-styles-for-contract-sections/

[wwalc]

I remember just one case when I needed headings inside lists and that was indeed some legal document. I wonder if such cases shouldn't be solved by styling. At least in the referenced article it would be more convenient to have a CSS rule for a contract, which makes the styling of list items dependent on the nesting level. The top-level list would then just have a "heading-like" style.

[iainhallam]

That's not particularly semantic, and doesn't cover the case where a list item begins with a heading then proceeds to have paragraphs about that topic, before the next list item, which also has its own heading and paragraphs. See Section 9 (pp. 12-13) of this model constitution which I recently had to try to mark up for a charity wanting it on their website: https://www.gov.uk/government/uploads/system/uploads/attachment_data/file/562468/Association_Model_Constitution.pdf

[treyspiva]

Another use case for the document list is procedures. You need a number list for the step of the procedure. Often pictures (but not limited to images) objects are needed to illustrate the procedure step. Having the image as a sibling of step breaks the numbering. It would be an awful solution to make the user have to set the start number in the next step.

Look at every web document type editor like notion, and paper. They all have a way to have more complex list. To not implement the document lists, you are settling to be a simple editor.

[JacDek]

I have a use case were Latex markup is being translated into html for editing in the Ckeditor. I would prefer that the editor didn't just drop elements that it decides are invalid. At the moment we are trying to find a workaround in the translation so that it will spit out something that is safe to give to Ckeditor.

[alexishuxley]

CkEditor has made its way into many downstream products, e.g. wikis, ticketing systems, project management systems.

Frequently in these contexts its necessary to write instructions, for which step numbering is an absolute must, and often these instructions need to include images or code samples. This is just the nature of quality documention. For example:

1. Scroll down the page to the share icon, which looks like this:
   
   and click it.
2. Select the recipient application.

The above two list items were both done in Github's editor with '1.' and '1.', where it is displayed correctly as '1.' and '2.', but in CkEditor itself it is not displayed correctly, which leads to conversations like:

I got as far as step 1 and then it went wrong.
Err, which step 1? The first step 1 or the second step 1?

[neongreen]

Frequently in these contexts its necessary to write instructions, for which step numbering is an absolute must, and often these instructions need to include images or code samples.

Same here. I run Brick.do; I asked a customer what they would require to start using Brick for writing documentation, and "lists with multiple elements inside" was the first thing they mentioned.

[jhartacs]

Using CKEditor 5 to write numbered instructions is impossible with the current approach. Specifically the lack of ability to add images that highlight an instruction. Lists with multiple elements inside is absolutely needed.

[kuku711]

it will resolve the issue of block elements like images/table inside a list? (right now its just reset the list numbers/remove)

[Reinmar]

it will resolve the issue of block elements like images/table inside a list? (right now its just reset the list numbers/remove)

Yes, that's exactly what this feature is all about :) 

[Reinmar]

To conclude this ticket:

It's been a long ride – nearly a year-long project. Definitely one of the trickiest feature we ever worked on.

Finally, it's over 🎉

Congratulations to @niegowski @arkflpc @CatStrategist @oleq @magda-chrzescian @scofalik and many other that contributed. Big thanks to the @ckeditor/qa-team 🤗

This feature will be a part of the upcoming v34.0.0 release. However, due to its size and complexity, we'll keep it on an "experimental" level for 1-2 releases, meaning that we don't recommend using it in production without assessing the risk. For now, it isn't even covered in the documentation, although this should change sooner.

[blairjanis]

I'm very interested in testing out the document list feature but I must be doing something wrong in the implementation. I'm importing DocumentList import DocumentList from '@ckeditor/ckeditor5-list/src/documentlist.js'; and adding DocumentList to the Editor.buildinPlugins array. But when I do that my toolbar disappears and the editor is not editable. No error is showing up in the console. Any help is appreciated. Thanks.

[FilipTokarski]

Hi @blairjanis as this ticket was a feature request and is already closed - could you open a new ticket with detailed reproduction steps, editor config, plugins installed, etc., so that we could be able to investigate it?