1[:octicons-file-code-24:][_tasklist]{: .source-link } 2 3# Tasklist 4 5## Overview 6 7The Tasklist extension adds GFM style task lists. They follow the same syntax as GFM. Simply start each list item with 8a square bracket pair containing either a space (an unchecked item) or a `x` (a checked item). 9 10!!! example "Task List Example" 11 12 All task lists in this documentation are generated with [`custom_checkbox`](#options) enabled. 13 14 === "Output" 15 Task List 16 17 - [X] item 1 18 * [X] item A 19 * [ ] item B 20 more text 21 + [x] item a 22 + [ ] item b 23 + [x] item c 24 * [X] item C 25 - [ ] item 2 26 - [ ] item 3 27 28 29 === "Markdown" 30 ``` 31 Task List 32 33 - [X] item 1 34 * [X] item A 35 * [ ] item B 36 more text 37 + [x] item a 38 + [ ] item b 39 + [x] item c 40 * [X] item C 41 - [ ] item 2 42 - [ ] item 3 43 ``` 44The Tasklist extension can be included in Python Markdown by using the following: 45 46```py3 47import markdown 48md = markdown.Markdown(extensions=['pymdownx.tasklist']) 49``` 50 51## Styling with CSS 52 53The HTML structure of a task list is found below: 54 55=== "Default" 56 57 This is the default output. 58 59 ```html 60 <ul class="task-list"> 61 <li class="task-list-item"> 62 <input type="checkbox" disabled="" checked=""> 63 item 1 64 </li> 65 </ul> 66 ``` 67 68=== "Custom" 69 If `custom_checkbox` is enabled, the structure will be as follows: 70 71 ```html 72 <ul class="task-list"> 73 <li class="task-list-item"> 74 <label class="task-list-control"> 75 <input type="checkbox" disabled checked=""> 76 <span class="task-list-indicator"></span> 77 </label> 78 item 1 79 </li> 80 </ul> 81 ``` 82 83=== "Clickable" 84 If `clickable_checkbox` is enabled, user interaction will be allowed by removing the `disabled` attribute from the 85 `input` element. `clickable_checkbox` can be a applied to either the default or custom form. 86 87 ```html 88 <ul class="task-list"> 89 <li class="task-list-item"> 90 <label class="task-list-control"> 91 <input type="checkbox" checked=""> 92 <span class="task-list-indicator"></span> 93 </label> 94 item 1 95 </li> 96 </ul> 97 ``` 98 99| Classes | Description | 100| --------------------- | ------------------------------------------------------------------------------------------------------ | 101| `task-list` | Attached to either the `ul` or `ol` tag and represents the entire list element. | 102| `task-list-item` | This is attached the `li` tag and represents an item in the list. | 103| `task-list-control` | This is attached to the `label` tag and represents the control object. | 104| `task-list-indicator` | This is attached to the `span` directly following the input and is used to style the visual indicator. | 105 106??? settings "CSS Setup" 107 108 === "Basic Tasklist" 109 In order to style these we mainly remove the list type style and adjust the margins to align with normal list 110 styles. 111 112 ```css 113 .markdown-body .task-list-item { 114 list-style-type: none !important; 115 } 116 117 .markdown-body .task-list-item input[type="checkbox"] { 118 margin: 0 4px 0.25em -20px; 119 vertical-align: middle; 120 } 121 ``` 122 123 === "Custom Tasklist" 124 125 If custom check box icons are desired, custom styles can be used to give a unique look to the check marks. 126 Below is a very simple CSS example that creates a light gray square with rounded corners and displays a green 127 Unicode check mark when the control is checked. This can be adapted to use web fonts, images, etc. 128 129 ```css 130 .markdown-body .task-list-item { 131 list-style-type: none !important; 132 } 133 134 .markdown-body .task-list-item input[type="checkbox"] { 135 margin: 0 4px 0.25em -20px; 136 vertical-align: middle; 137 } 138 139 .markdown-body .task-list-control { 140 display: inline; /* Ensure label is inline incase theme sets it to block.*/ 141 } 142 143 .markdown-body .task-list-control { 144 position: relative; 145 display: inline-block; 146 color: #555; 147 cursor: pointer; 148 } 149 150 .markdown-body .task-list-control input[type="checkbox"] { 151 position: absolute; 152 opacity: 0; 153 z-index: -1; /* Put the input behind the label so it doesn't overlay text */ 154 } 155 156 .markdown-body .task-list-indicator { 157 position: absolute; 158 top: -8px; 159 left: -18px; 160 display: block; 161 width: 14px; 162 height: 14px; 163 color: #eee; 164 background-color: #eee; 165 border-radius: .25rem; 166 } 167 168 .markdown-body .task-list-control input[type="checkbox"]:checked + .task-list-indicator::before { 169 display: block; 170 margin-top: -4px; 171 margin-left: 2px; 172 font-size: 16px; 173 line-height: 1; 174 content: "✔"; 175 color: #1EBB52; 176 } 177 ``` 178 179## Options 180 181Option | Type | Default | Description 182-------------------- | ---- | ------------ | ------------ 183`custom_checkbox` | bool | `#!py3 False` | Generate task lists in such a way as to allow for styling the check box with CSS. 184`clickable_checkbox` | bool | `#!py3 False` | Enable user to interact with checkboxes. 185