@@ -278,107 +278,187 @@ We use the following definitions when discussing indexing into arrays:
278
278
279
279
## Headings
280
280
281
- - Icon: ` headings `
282
- - Highlight: ` highlights.heading.backgrounds ` & ` highlights.heading.backgrounds `
283
- - Style: N/A
284
-
285
- - The icons replace the ` # ` characters in front of headings
286
- - The number of ` # ` characters in the heading determines the level of the heading
287
- - The level is used to index into the icon table using a cycle
288
- - The icon is left padded with spaces to fill the gap and hide any additional ` # `
289
- - The level is also used to index into both highlights tables using a clamp
290
- - Both are applied to the icon and the background extends through the entire line
281
+ ``` lua
282
+ require (' render-markdown' ).setup ({
283
+ -- Replaces '#+' of 'atx_h._marker'
284
+ -- The number of '#' in the heading determines the 'level'
285
+ -- The 'level' is used to index into the array using a cycle
286
+ -- The result is left padded with spaces to hide any additional '#'
287
+ headings = { ' ' , ' ' , ' ' , ' ' , ' ' , ' ' },
288
+ highlights = {
289
+ heading = {
290
+ -- The 'level' is used to index into the array using a clamp
291
+ -- Applies to the heading icon and extends through the entire line
292
+ backgrounds = { ' DiffAdd' , ' DiffChange' , ' DiffDelete' },
293
+ -- The 'level' is used to index into the array using a clamp
294
+ -- Applies to the heading icon only
295
+ foregrounds = { ' markdownH1' , ' markdownH2' , ' markdownH3' , ' markdownH4' , ' markdownH5' , ' markdownH6' },
296
+ },
297
+ },
298
+ })
299
+ ```
291
300
292
301
## Dashed Line
293
302
294
- - Icon: ` dash `
295
- - Highlight: ` highlights.dash `
296
- - Style: N/A
297
-
298
- - Gets repeated across the window's width when a ` thematic_break ` is found
303
+ ``` lua
304
+ require (' render-markdown' ).setup ({
305
+ -- Replaces '---'|'***'|'___'|'* * *' of 'thematic_break'
306
+ -- The icon gets repeated across the window's width
307
+ dash = ' ─' ,
308
+ highlights = {
309
+ -- Applies to the whole line generated from the icon
310
+ dash = ' LineNr' ,
311
+ },
312
+ })
313
+ ```
299
314
300
315
## List Bullets
301
316
302
- - Icon: ` bullets `
303
- - Highlight: ` highlights.bullet `
304
- - Style: N/A
305
-
306
- - The icons replace the ` - ` , ` + ` , and ` * ` characters in front of list items
307
- - How deeply nested the list is determines the level of the list
308
- - The level is used to index into the icon table using a cycle
309
- - If the item is a ` checkbox ` a conceal is instead used to hide the bullet
317
+ ``` lua
318
+ require (' render-markdown' ).setup ({
319
+ -- Replaces '-'|'+'|'*' of 'list_item'
320
+ -- How deeply nested the list is determines the 'level'
321
+ -- The 'level' is used to index into the array using a cycle
322
+ -- If the item is a 'checkbox' a conceal is used to hide the bullet instead
323
+ bullets = { ' ●' , ' ○' , ' ◆' , ' ◇' },
324
+ highlights = {
325
+ -- Applies the bullet icon
326
+ bullet = ' Normal' ,
327
+ },
328
+ })
329
+ ```
310
330
311
331
## Checkboxes
312
332
313
- - Icon: ` checkbox.unchecked ` , ` checkbox.checkbox ` , & ` checkbox.custom.rendered `
314
- - Highlight: ` highlights.checkbox.unchecked ` , ` highlights.checkbox.checked ` , & ` checkbox.custom.highlight `
315
- - Style: N/A
316
-
317
- - In the case of a standard checked ` [x] ` or unchecked ` [ ] ` checkbox state we simply
318
- overlay the appropriate icon and apply the appropriate highlight
319
-
320
- - Custom checkbox states setup through ` checkbox.custom ` are more involved as they
321
- are not part of the actual ` markdown ` grammar
322
- - As a result this requires neovim >= ` 0.10.0 ` since it relies on ` inline ` extmarks
323
- - An example comes with the default config:
324
- ` todo = { raw = '[-]', rendered = ' ', highlight = '@markup.raw' } `
325
- - The key part in this case ` todo ` is unused. The parts of the value are:
326
- - ` raw ` : matched against the raw text of a ` shortcut_link `
327
- - ` rendered ` : replaces the ` raw ` value when rendering
328
- - ` highlight ` : color used for ` rendered ` text
333
+ ``` lua
334
+ require (' render-markdown' ).setup ({
335
+ -- Checkboxes are a special instance of a 'list_item' that start with a 'shortcut_link'
336
+ -- There are two special states for unchecked & checked defined in the markdown grammar
337
+ checkbox = {
338
+ -- Replaces '[ ]' of 'task_list_marker_unchecked'
339
+ unchecked = ' ' ,
340
+ -- Replaces '[x]' of 'task_list_marker_checked'
341
+ checked = ' ' ,
342
+ -- Define custom checkbox states, more involved as they are not part of the markdown grammar
343
+ -- As a result this requires neovim >= 0.10.0 since it relies on 'inline' extmarks
344
+ -- Can specify as many additional states as you like following the 'todo' pattern below
345
+ custom = {
346
+ -- The key in this case `todo` is unused
347
+ todo = {
348
+ -- Matched against the raw text of a 'shortcut_link'
349
+ raw = ' [-]' ,
350
+ -- Replaces the 'raw' value when rendering
351
+ rendered = ' ' ,
352
+ -- Applies to the 'rendered' icon
353
+ highlight = ' @markup.raw'
354
+ },
355
+ },
356
+ },
357
+ highlights = {
358
+ checkbox = {
359
+ -- Applies to the unchecked icon
360
+ unchecked = ' @markup.list.unchecked' ,
361
+ -- Applies to the checked icon
362
+ checked = ' @markup.heading' ,
363
+ },
364
+ },
365
+ })
366
+ ```
329
367
330
368
## Standard Quotes
331
369
332
- - Icon: ` quote `
333
- - Highlight: ` highlights.quote `
334
- - Style: N/A
335
-
336
- - The icon replaces the ` | ` character in front of ` block_quotes `
370
+ ``` lua
371
+ require (' render-markdown' ).setup ({
372
+ -- Replaces '>' of 'block_quote'
373
+ quote = ' ▋' ,
374
+ highlights = {
375
+ -- Applies to the quote icon
376
+ quote = ' @markup.quote' ,
377
+ },
378
+ })
379
+ ```
337
380
338
381
## Callouts
339
382
340
- - Icon: ` callout ` & ` callout.custom.rendered `
341
- - Highlight: ` highlights.callout ` & ` callout.custom.highlight `
342
- - Style: N/A
343
-
344
- - Callouts are a special instance of a ` block_quote ` that start with a ` shortcut_link `
345
- - When this pattern is seen the link text gets replaced by the icon
346
- - The highlight is then applied to the icon as well as the quote markers
347
-
348
- - Custom callouts setup through ` callout.custom ` behave in much the same way
349
- - An example comes with the default config:
350
- ` bug = { raw = '[!BUG]', rendered = ' Bug', highlight = 'DiagnosticError' } `
351
- - The key part in this case ` bug ` is unused. The parts of the value are:
352
- - ` raw ` : matched against the raw text of a ` shortcut_link `
353
- - ` rendered ` : replaces the ` raw ` value when rendering
354
- - ` highlight ` : color used for ` rendered ` text
383
+ ``` lua
384
+ require (' render-markdown' ).setup ({
385
+ -- Callouts are a special instance of a 'block_quote' that start with a 'shortcut_link'
386
+ callout = {
387
+ -- Replaces '[!NOTE]'
388
+ note = ' Note' ,
389
+ -- Replaces '[!TIP]'
390
+ tip = ' Tip' ,
391
+ -- Replaces '[!IMPORTANT]'
392
+ important = ' Important' ,
393
+ -- Replaces '[!WARNING]'
394
+ warning = ' Warning' ,
395
+ -- Replaces '[!CAUTION]'
396
+ caution = ' Caution' ,
397
+ -- Define custom callouts, can specify as many as you like following the 'bug' pattern below
398
+ custom = {
399
+ -- The key in this case `bug` is unused
400
+ bug = {
401
+ -- Matched against the raw text of a 'shortcut_link'
402
+ raw = ' [!BUG]' ,
403
+ -- Replaces the 'raw' value when rendering
404
+ rendered = ' Bug' ,
405
+ -- Applies to the 'rendered' text and quote markers
406
+ highlight = ' DiagnosticError' ,
407
+ },
408
+ },
409
+ },
410
+ highlights = {
411
+ -- Used for standard callouts, applies to both text and quote markers
412
+ callout = {
413
+ note = ' DiagnosticInfo' ,
414
+ tip = ' DiagnosticOk' ,
415
+ important = ' DiagnosticHint' ,
416
+ warning = ' DiagnosticWarn' ,
417
+ caution = ' DiagnosticError' ,
418
+ },
419
+ },
420
+ })
421
+ ```
355
422
356
423
## Code Blocks
357
424
358
- - Icon: N/A
359
- - Highlight: ` highlights.code `
360
- - Style: ` code_style `
361
-
362
- - ` code_style ` determines how code blocks are rendered:
363
- - ` none ` : disables all rendering
364
- - ` normal ` : adds highlight group to the code block
365
- - ` full ` : ` normal ` + language icon & name above the code block
425
+ ``` lua
426
+ require (' render-markdown' ).setup ({
427
+ -- Determines how code blocks are rendered:
428
+ -- none: disables all rendering
429
+ -- normal: adds highlight group to the code block
430
+ -- full: normal + language icon & name above the code block
431
+ code_style = ' full' ,
432
+ highlights = {
433
+ -- Applies to code blocks
434
+ code = ' ColorColumn' ,
435
+ },
436
+ })
437
+ ```
366
438
367
439
## Tables
368
440
369
- - Icon: N/A
370
- - Highlight: ` highlights.table.head ` & ` highlights.table.row `
371
- - Style: ` table_style ` & ` cell_style `
372
-
373
- - The ` head ` highlight is used for the table heading, delimitter, and the line above
374
- - The ` row ` highlight is used for everything else, main table rows and the line below
375
- - ` table_style ` determines how the table as a whole is rendered:
376
- - ` none ` : disables all rendering
377
- - ` normal ` : applies the ` cell_style ` rendering to each row of the table
378
- - ` full ` : ` normal ` + a top & bottom line that fill out the table when lengths match
379
- - ` cell_style ` determines how individual cells of a table are rendered:
380
- - ` overlay ` : writes completely over the table, removing conceal behavior and highlights
381
- - ` raw ` : replaces only the ` | ` icons in each row, leaving the cell completely unmodified
441
+ ``` lua
442
+ require (' render-markdown' ).setup ({
443
+ -- Determines how the table as a whole is rendered:
444
+ -- none: disables all rendering
445
+ -- normal: applies the 'cell_style' rendering to each row of the table
446
+ -- full: normal + a top & bottom line that fill out the table when lengths match
447
+ table_style = ' full' ,
448
+ -- Determines how individual cells of a table are rendered:
449
+ -- overlay: writes completely over the table, removing conceal behavior and highlights
450
+ -- raw: replaces only the '|' characters in each row, leaving the cells completely unmodified
451
+ cell_style = ' overlay' ,
452
+ highlights = {
453
+ table = {
454
+ -- Applies to table heading, delimitter, and the line above
455
+ head = ' @markup.heading' ,
456
+ -- Applies to everything else, main table rows and the line below
457
+ row = ' Normal' ,
458
+ },
459
+ },
460
+ })
461
+ ```
382
462
383
463
# Additional Info
384
464
0 commit comments