search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.63k stars 8.51k forks source link

Task lists are rendered as disabled and with dashes #5409

Closed barrymcgee closed 3 years ago

barrymcgee commented 3 years ago

🐛 Bug Report

Prerequisites

Description

Task list markdown syntax as follows does not render as it does on Github:

- [  ] task 1
- [  ] task 2
- [  ] task 3

I'd expect the above to render as a list of checkboxes without the preceding dash that can be clicked like so;

Instead it renders like so;

Screenshot 2021-08-23 at 14 47 19

Have you read the Contributing Guidelines on issues?

Yes

Steps to reproduce

https://codesandbox.io/s/unruffled-shape-3m6td?file=/docs/intro.md

  1. See the task list retains the dash before the checkboxes
  2. Checkboxes cannot be clicked

Expected behavior

Actual behavior

(Write what happened. Add full console log messages and screenshots, if applicable.)

Your environment

Reproducible demo

https://3m6td.sse.codesandbox.io/docs/intro

slorber commented 3 years ago

Hi

Task lists are not std common marks. I'm surprised that our parser MDX has native support for this out of the box.

I don't think this is a bug, but this is definitively an UI improvement we could add by default.

In the meantime you can achieve this with custom site CSS:


ul.contains-task-list {
    margin-left: 0;
    padding-left: 0;
    list-style-type: none;
}
SamarthAroraa commented 3 years ago

Hi @slorber, I would like to work on this issue.

barrymcgee commented 3 years ago

Hi @slorber - the custom styling will remove the list bullets but the inputs will still be disabled as they are parsed with a disabled attribute to the <input /> tag.

I know task lists are not native to standard markdown but as Docusaurus states that it supports GFM (Github Flavored Markdown), I'd expect it to reflect how Markdown is rendered on Github. Perhaps that is an incorrect assumption on my part.

slorber commented 3 years ago

@barrymcgee what do you expect? that clicking the checkbox would check it and you end-up with [x] in your git repo?

This would require for the UI to actually be able to commit to Git. Otherwise, the checkbox would be checkable but only locally and would not be persisted anywhere, and that seems an even weirder thing to want.

Thanks @SamarthAroraa PR welcome

barrymcgee commented 3 years ago

To be honest, I hadn't given much thought to the implementation details of a solution beyond highlighting the first principle that I'd expect a list of checkboxes to be clickable at some point, otherwise it's pointless rendering a list of checkboxes at all.

The use case where this presented in my team was in a list of actions to investigate in the event you get pinged when on-call. I initially expect these to persisted locally via localStorage or whatever but thinking about it more, you then hit the problem of when to purge etc which quickly becomes a significant overreach for a static site generator.

As such, I think the best solution is not to render checkboxes at all. The markdown syntax that generates a task list on GitHub should render as plain text when using Docusaurus. </two cents>

slorber commented 3 years ago

I'd expect a list of checkboxes to be clickable at some point, otherwise it's pointless rendering a list of checkboxes at all.

I don't agree, rendering checkboxes that you can click still make sense to me if you want to create a task list that you edit through MD edits and Git commits. Note technically, checking a checkbox on GitHub is just a shortcut over editing the issue md content. In the case of Git, this shortcut is just technically harder to build in a non-opinionated way.

Also remember that when you look at a Github Issue with checkboxes and you have read-only permission, GitHub also render read-only checkboxes for you. Example:

You shouldn't be able to click those checkboxes, similarly to the current Docusaurus behavior.

I believe we do support correctly checkboxes, similarly to what GitHub does. The "edit shortcut" is not GitHub Flavored Markdown, it's something extra they built on top.

I initially expect these to persisted locally via localStorage or whatever but thinking about it more, you then hit the problem of when to purge etc which quickly becomes a significant overreach for a static site generator.

Local storage is something that totally doesn't make sense to me. It's persisted only for you, and only in a single browser. It's very unlikely we'll add anything based on Localstorage to Docusaurus mdx checkboxes by default, but you can build this yourself using MDX or a remark plugin if you really want that.

As such, I think the best solution is not to render checkboxes at all. The markdown syntax that generates a task list on GitHub should render as plain text when using Docusaurus. </two cents>

This behavior is provided by our parser MDX (I think, it's not Docusaurus at least), I'm not even sure we can disable it. If you really want to disable it for some reason, you can probably build a custom remark plugin to do so.

Why would you want to render [ ] as plain text? Why use [ ] in the first place in this case?

I still think it's valuable to render non-clickable checkboxes in some cases. For example, I could add checkboxes to our Docusaurus v2 beta blog post for each task we mention:

https://docusaurus.io/blog/2021/05/12/announcing-docusaurus-two-beta#whats-next

Some of those tasks have been handled already and I could mark them as checked:

image

(I personally prefer a checkbox compared to strikethrough)

I don't think we are going to do anything with this issue, so closing it for now.

As you can build more advanced features with custom Remark plugins, I suggest you do so, and if you present us a concrete UX that we can play with and it makes sense, then maybe we'll add it to Docusaurus.

slorber commented 3 years ago

Re-opening because still think we should render without the dash, cc @SamarthAroraa

SamarthAroraa commented 3 years ago

Hi @slorber, I see that the unwanted behaviour (dashed checkboxes) is present in the original MDX parser library. The most natural solution that occurred to me was to overwrite the CSS with our own CSS, 

ul.contains-task-list {
    margin-left: 0;
    padding-left: 0;
    list-style-type: none;
}

as you mentioned in your comment. However, since I am a bit new to the project architecture and open source in general, I could not identify where to include this CSS to overwrite the default MDX behavior. From my personal codebase exploration, it seems to be somewhere in the Docusaurus MDX Loader directory.

I apologize for the delay and any inconvenience caused. Hoping to get up to speed as soon as possible and freely contribute more to this awesome repository!

slorber commented 3 years ago

@SamarthAroraa thanks

It's a theming concern related to MDX, I would put it there:

docusaurus/packages/docusaurus-theme-classic/src/theme/MDXComponents/styles.css

akshitarora921 commented 3 years ago

Hi, I would like to help :).

himanshu007-creator commented 3 years ago

Hi @SamarthAroraa, can you please drop a "HI" confirming you are working in the issue, otherwise i can work on the issue