add checkbox list to GFM

[fdschneider]

To create ToDo lists I love GitHubs checkbox list syntax:

- [x] this is still to do
- [ ] done 

renders as

• this is still to do
• done

I would like to use this on a Jekyll page. Also, kramdowns GFM parser (#68) is fairly incomplete, so it would be great to include it. Anybody out there who is interested in implementing this?

[gettalong]

I'm closing this for now but I'm happy to consider a pull request. However, there is no real specification of Github's flavor of Markdown so it is hard to be completely compatible to them.

[fdschneider]

Yes. I understand.

For Jekyll, the checkboxes are a thing that can easily be solved via a plugin or even liquid filters plus some css. I settled for the latter, since it works on GitHub pages:

 {{ content | replace: '<li>[ ]', '<li class = "box">' | replace: '<li>[x]', '<li class = "box_done">'  }}

Thanks, anyway.

[zerocool4u2]

you can just replace the text before passing it to the kramdown parser

raw_text.gsub(/(\d+\. |\* )\K\[(x|X)\]/, %(<i class="fa fa-check-square-o"></i>)).gsub(/(\d+\. |\* )\K\[ \]/, %(<i class="fa fa-square-o"></i>))

FontAwesome example

\K will work only on ruby 2.0 and above, it's like a lookbehind, but will work with the + and | (or) escape chars, keep in mind that will also replace the code on code blocks, i guess you could use a more complex regexp if that is an issue
http://rubular.com/r/wvxaX8jKtX
http://rubular.com/r/5hMGNPFl87

[alequartz]

@gettalong I am following the gitlab discussions on this topic. Apparently they would be willing to switch to kramdown if the checkbox lists are implemented. I cannot hide that I am totally in favour.
Would the solution from @zerocool4u2 work for you? Are you still open to pull requests on this ?

Thank you for all your work

[gettalong]

@alequartz Yes, pull requests are welcome. Note, however, that this can only be an enhanced to the GFM parser, not to the main kramdown parser.

The first thing to be done would be to define the required output. Github seems to output this for the example of @fdschneider:

<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled=""> this is still to do</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" checked="" disabled=""> done</li>
</ul>

So is this compatible with the way Gitlab renders task lists?

[alequartz]

@gettalong. This is what I get using the same syntax in gitlab. Pretty similar. Except for the ul class. I suggest we stick with the github class.

<ul class="task-list" dir="auto">
   <li class="task-list-item">
      <input type="checkbox" class="task-list-item-checkbox" disabled=""> this is still to do
   </li>
   <li class="task-list-item">
      <input type="checkbox" class="task-list-item-checkbox" checked="" disabled=""> done
   </li>
</ul>

[gettalong]

@alequartz Thanks for looking this up!

So a pull request for the GFM parser needs to do the following:

• Add the class contains-task-list to the unordered (or ordered) list tag (i.e. to the <ul> or <ol> tag)
• Parse the start of a list item for the character sequences \[ \]\s+\S and \[x\]\s+\S (i.e. square brackets with a single space character or an x/X, followed by at least one whitespace character and then at least one non-whitespace character) and convert the sequence to an <input> tag with the appropriate attributes.

[alequartz]

@gettalong Agreed.
Concerning your previous comment.

Note, however, that this can only be an enhanced to the GFM parser, not to the main kramdown parser.

I apologise beforehand of my lack of ruby know-how. What I understand is that the code should be added to the GFM class. But how does this class interact with the main kramdown parser. For example, do we need to re-implement all the code responsible for list parsing ?

[gettalong]

@alequartz There are various possibilities. However, if I would tackle this I wouldn't re-implement list parsing since it is already a rather complex part of the kramdown parser. I probably would just let kramdown's list parser do its thing and then post-process all list items to see if they contain task items.

[alequartz]

@gettalong I am happy I asked.
If you can point me in the right direction (where the post-processing is happening) I am willing to give it a try. But if you already know where to put you hands I think it's faster if you do it. If so, let me know how I can provide additional help.

[zerocool4u2]

I'm not involved in the project, but i believe it would be in lib/kramdown/parser/gfm.rb, there you can bypass the input and make the replace(gsub), i think it would be appropriated to have an option for this, since this implementation may be a problem in code blocks. With that said, a better option would be

kramdown/lib/kramdown/converter/html.rb

Line 155 in f4cdae2

def convert_li(el, indent)

and use an alternative render for li's if gfm_quirks "gh-todo-lists" is selected as an option, check the [x] with the regex and replace with the content expected for the check-boxes, if is implemented here it would not be a problem in code blocks or other cases, take in mind that what i posted before is kinda a hack since is just giving raw html to the parser and it wasn't thinked to work in the flow of kramdown, if you really want to implement this html.rb seems to be a good place, i believe that "res" is the variable with the content, but I'm not really sure.

[gettalong]

@alequartz I could certainly implement it but I won't use my time for this. I will, however, accept pull requests.

@zerocool4u2 What I meant was overriding the parser method, calling the overridden method, iterating through the generated list items and replacing the task item markers.

Moving this to the converter is not the better option. This change should be GFM specific and therefore be handled in the GFM parser.