SnakeMD 0.10.x Features Checklists

SnakeMD 0.10.x Features Checklists Featured Image

SnakeMD is one of those projects I put together for myself that has sort of outgrown my own use. As a result, I figured it was time to start documenting its growth.

Table of Contents

What Are Checklists?

If you’re familiar with Markdown, you probably already know the syntax to create a list. In general, there are two types of list syntaxes: ordered and unordered. They look like this:

- This
- is
- an
- unordered
- list
1. This
2. is
3. an
4. ordered
5. list

Naturally, these lists render as follows:

  • This
  • is
  • an
  • unordered
  • list
  1. This
  2. is
  3. an
  4. ordered
  5. list

Now, as it turns out, some flavors of Markdown (or possibly all, I’m not sure) support checklists. To create a checklist, we take the syntax of the unordered list (though I believe this works in either cases) and add a set of square brackets to it as follows:

- [ ] This
- [ ] is
- [ ] a
- [ ] checklist

Checklists are pretty cool because you can also mark the individual checkboxes as completed:

- [ ] This
- [x] is
- [ ] a
- [x] checklist

And you’ll get something that looks like this (thanks, GitHub):

  • This
  • is
  • a
  • checklist

In this update, one user, Bass-03Opens in a new tab., added this feature, so now you too can add checklists to your Python code as follows:

import snakemd
doc = snakemd.new_doc("README")
doc.add_checklist(
    [
        "Pass the puck",
        "Shoot the puck",
        "Score a goal"
    ]
)

And of course, the update includes various ways to create these lists. For example, you can use the new MDCheckListOpens in a new tab. object to control whether or not the items start checked or unchecked. Similarly, you can use the new CheckBoxOpens in a new tab. object to control the checked status of individual items.

Why Add Checklists?

There are basically two main reasons you might add checklists to a Markdown generation package. First, you might include checklists because checklists are a fairly standard feature in Markdown. At the very least, it’s a feature that’s supported in GitHub markdown which is a tool that I use often.

Second, you might include checklists because you have a personal need for the feature. Here’s what Bass-03 is planning to use the feature for:

Just as background, I am going to use this package to turn a todoist export to markdown, so I can import it into taskade. Final product will be Todoist Projects turned into Markdown, which could be used on any markdown editor of course.

Project here https://gitlab.com/mundo03/todoist-exportOpens in a new tab.

GitHub CommentOpens in a new tab.

Certainly, I’m starting to think of ways this feature might be useful.

How Do Checklists Work?

For those of you interested in how checklists work under the hood, it’s helpful to understand how the package is designed. At its core, SnakeMD is an object-oriented script which leverages objects for each of the type of elements you can add to a Markdown file. For example, the library features objects for paragraphs, tables, and lists.

Now, when I was originally designing the library, I wanted to make it as easy to use as possible. As a result, the objects aren’t the central focus of the package. Instead, I have a `new_doc` function which is used to generate the Document object. From there, Document supports dozens of methods for creating the various elements you might want in a Markdown document.

The reason for designing the package this way is pretty simple. Objects in Python are a pain to use! For example, without the handy methods defined in Document, you would have to import a separate class every time you need it. With the current design, you just need to import `snakemd` and the implicit Document object will give you all the functionality you probably need.

If you’re unconvinced of this design, no worries! I happen to like it because it’s very similar to the express library provided by Plotly. If you want a bar graph but don’t care about all the ways you might customize it, just dump your dataframe into the express bar plot function. The same idea applies with SnakeMD.

With that out of the way, let’s talk about how checklists work. First, checklists are essentially MDLists under the hood. After all, the only difference between a checklist and an unordered list are the square brackets. The way Bass-03 designed the change was to create a new class called MDCheckList that extends MDList. It would then render the items according to the rules of MDList while inserting those square brackets where needed.

Of course, the drawback of this design is granularity. In short, you don’t really have control over whether or not each item is checked. As a result, Bass-03 included a CheckBox object which could be used in combination with an MDList to inject the checkboxes.

Finally, I wrapped the MDChecklist class into the `add_checklist` method to allow folks to quickly create checklists from a list of items.

Plans for the Future?

Now that the checklists are a part of the package, I was able to include an example in the main README. Beyond that, the only changes are in the documentation, which pull from the package directly.

Looking forward, I don’t have a lot of immediate plans for the library. In general, I’m just happy that people are using it. If you’re interested in helping out yourself, check out the list of issuesOpens in a new tab..

Otherwise, here are some other things I’ve been working on:

As always, thanks again for checking out the site!

SnakeMD News (2 Articles)—Series Navigation

SnakeMD is a Python package that allows users to generate Markdown.

Jeremy Grifski

Jeremy grew up in a small town where he enjoyed playing soccer and video games, practicing taekwondo, and trading Pokémon cards. Once out of the nest, he pursued a Bachelors in Computer Engineering with a minor in Game Design. After college, he spent about two years writing software for a major engineering company. Then, he earned a master's in Computer Science and Engineering. Today, he pursues a PhD in Engineering Education in order to ultimately land a teaching gig. In his spare time, Jeremy enjoys spending time with his wife, playing Overwatch and Phantasy Star Online 2, practicing trombone, watching Penguins hockey, and traveling the world.

Recent Posts