Skip to content

Commit d2a132e

Browse files
Use lua for documenting components
1 parent 7b8110b commit d2a132e

File tree

3 files changed

+328
-157
lines changed

3 files changed

+328
-157
lines changed

CHANGELOG.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Change Log
22

3+
## 3.3.1 (2024-07-08)
4+
5+
### Features
6+
7+
- Improved health [7b8110b](https://github.com/MeanderingProgrammer/markdown.nvim/commit/7b8110b675766810edcbe665f53479893b02f989)
8+
39
## 3.3.0 (2024-07-06)
410

511
### Features
@@ -43,7 +49,7 @@
4349

4450
- Get mode at time of event instead of callback execution: [#36](https://github.com/MeanderingProgrammer/markdown.nvim/issues/36)
4551
[b556210](https://github.com/MeanderingProgrammer/markdown.nvim/commit/b556210e6c8759b7d23d5bc74c84aaafe2304da4)
46-
- Update healthcheck to work with neovim 0.9.5: [64969bc](https://github.com/MeanderingProgrammer/markdown.nvim/commit/64969bc94a9d633dc23b59a382cab407c99fecb1)
52+
- Update health check to work with neovim 0.9.5: [64969bc](https://github.com/MeanderingProgrammer/markdown.nvim/commit/64969bc94a9d633dc23b59a382cab407c99fecb1)
4753
- Handle block quotes with empty lines: [#41](https://github.com/MeanderingProgrammer/markdown.nvim/issues/41)
4854
[6f64bf6](https://github.com/MeanderingProgrammer/markdown.nvim/commit/6f64bf645b817ff493a28925b1872a69d07fc094)
4955

README.md

Lines changed: 160 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -278,107 +278,187 @@ We use the following definitions when discussing indexing into arrays:
278278

279279
## Headings
280280

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+
```
291300

292301
## Dashed Line
293302

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+
```
299314

300315
## List Bullets
301316

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+
```
310330

311331
## Checkboxes
312332

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+
```
329367

330368
## Standard Quotes
331369

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+
```
337380

338381
## Callouts
339382

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+
```
355422

356423
## Code Blocks
357424

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+
```
366438

367439
## Tables
368440

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+
```
382462

383463
# Additional Info
384464

0 commit comments

Comments
 (0)