Skip to content

Commit cdc58f5

Browse files
MeanderingProgrammerMeanderingProgrammer
committed
Use panvimdoc locally to generate documenation from README
1 parent c221998 commit cdc58f5

File tree

3 files changed

+204
-1
lines changed

3 files changed

+204
-1
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Plugin to improve viewing Markdown files in Neovim
4040
}
4141
```
4242

43-
## Default Config
43+
# Setup
4444

4545
Below is the configuration that gets used by default, any part of it can be modified
4646
by the user.

‎doc/render-markdown.txt

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
*render-markdown.txt* For 0.9.5 Last change: 2024 March 27
2+
3+
==============================================================================
4+
Table of Contents *render-markdown-table-of-contents*
5+
6+
1. markdown.nvim |render-markdown-markdown.nvim|
7+
2. Features |render-markdown-features|
8+
3. Dependencies |render-markdown-dependencies|
9+
4. Install |render-markdown-install|
10+
- Lazy.nvim |render-markdown-install-lazy.nvim|
11+
5. Setup |render-markdown-setup|
12+
6. Commands |render-markdown-commands|
13+
7. Purpose |render-markdown-purpose|
14+
8. Related Projects |render-markdown-related-projects|
15+
16+
==============================================================================
17+
1. markdown.nvim *render-markdown-markdown.nvim*
18+
19+
Plugin to improve viewing Markdown files in Neovim
20+
21+
22+
==============================================================================
23+
2. Features *render-markdown-features*
24+
25+
- Functions entirely inside of Neovim with no external windows
26+
- Changes between `rendered` view in normal mode and `raw` view in all other modes
27+
- Changes `conceallevel` between `rendered` and `raw` view based on configuration
28+
- Supports rendering `markdown` injected into other file types
29+
- Highlights headings with different groups depending on level and replaces `#`
30+
- Highlights code blocks and inline code to better stand out
31+
- Replaces whichever style bullet point is being used with provided character
32+
- Replaces block quote leading `>` with provided character
33+
- Updates table borders with better border characters, does NOT automatically align
34+
- Basic support for `LaTeX` if `pylatexenc` is installed on system
35+
36+
37+
==============================================================================
38+
3. Dependencies *render-markdown-dependencies*
39+
40+
- markdown & markdown_inline <https://github.com/tree-sitter-grammars/tree-sitter-markdown>
41+
parsers for treesitter <https://github.com/nvim-treesitter/nvim-treesitter>: Used to parse
42+
`markdown` files
43+
- pylatexenc <https://pypi.org/project/pylatexenc/>: Used to transform `LaTeX` strings
44+
to appropriate unicode using `latex2text`, not a mandatory dependency
45+
46+
47+
==============================================================================
48+
4. Install *render-markdown-install*
49+
50+
51+
LAZY.NVIM *render-markdown-install-lazy.nvim*
52+
53+
>lua
54+
{
55+
'MeanderingProgrammer/markdown.nvim',
56+
name = 'render-markdown', -- Only needed if you have another plugin named markdown.nvim
57+
dependencies = { 'nvim-treesitter/nvim-treesitter' },
58+
config = function()
59+
require('render-markdown').setup({})
60+
end,
61+
}
62+
<
63+
64+
65+
==============================================================================
66+
5. Setup *render-markdown-setup*
67+
68+
Below is the configuration that gets used by default, any part of it can be
69+
modified by the user.
70+
71+
>lua
72+
require('render-markdown').setup({
73+
-- Capture groups that get pulled from markdown
74+
markdown_query = [[
75+
(atx_heading [
76+
(atx_h1_marker)
77+
(atx_h2_marker)
78+
(atx_h3_marker)
79+
(atx_h4_marker)
80+
(atx_h5_marker)
81+
(atx_h6_marker)
82+
] @heading)
83+
84+
(fenced_code_block) @code
85+
86+
[
87+
(list_marker_plus)
88+
(list_marker_minus)
89+
(list_marker_star)
90+
] @list_marker
91+
92+
(block_quote (block_quote_marker) @quote_marker)
93+
(block_quote (paragraph (inline (block_continuation) @quote_marker)))
94+
95+
(pipe_table_header) @table_head
96+
(pipe_table_delimiter_row) @table_delim
97+
(pipe_table_row) @table_row
98+
]],
99+
-- Capture groups that get pulled from inline markdown
100+
inline_query = [[
101+
(code_span) @code
102+
]],
103+
-- Filetypes this plugin will run on
104+
file_types = { 'markdown' },
105+
-- Vim modes that will show a rendered view of the markdown file
106+
-- All other modes will be uneffected by this plugin
107+
render_modes = { 'n', 'c' },
108+
-- Characters that will replace the # at the start of headings
109+
headings = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
110+
-- Character to use for the bullet point in lists
111+
bullet = '○',
112+
-- Character that will replace the > at the start of block quotes
113+
quote = '┃',
114+
-- See :h 'conceallevel' for more information about meaning of values
115+
conceal = {
116+
-- conceallevel used for buffer when not being rendered, get user setting
117+
default = vim.opt.conceallevel:get(),
118+
-- conceallevel used for buffer when being rendered
119+
rendered = 3,
120+
},
121+
-- Define the highlight groups to use when rendering various components
122+
highlights = {
123+
heading = {
124+
-- Background of heading line
125+
backgrounds = { 'DiffAdd', 'DiffChange', 'DiffDelete' },
126+
-- Foreground of heading character only
127+
foregrounds = {
128+
'markdownH1',
129+
'markdownH2',
130+
'markdownH3',
131+
'markdownH4',
132+
'markdownH5',
133+
'markdownH6',
134+
},
135+
},
136+
-- Code blocks
137+
code = 'ColorColumn',
138+
-- Bullet points in list
139+
bullet = 'Normal',
140+
table = {
141+
-- Header of a markdown table
142+
head = '@markup.heading',
143+
-- Non header rows in a markdown table
144+
row = 'Normal',
145+
},
146+
-- LaTeX blocks
147+
latex = '@markup.math',
148+
-- Quote character in a block quote
149+
quote = '@markup.quote',
150+
},
151+
})
152+
<
153+
154+
155+
==============================================================================
156+
6. Commands *render-markdown-commands*
157+
158+
`:RenderMarkdownToggle` - Switch between enabling & disabling this plugin
159+
160+
- Function can also be accessed directly through `require('render-markdown').toggle()`
161+
162+
163+
==============================================================================
164+
7. Purpose *render-markdown-purpose*
165+
166+
There are many existing markdown rendering plugins in the Neovim ecosystem.
167+
However, most of these rely on syncing a separate browser window with the
168+
buffer. This is the correct way to do things to get full feature support,
169+
however I wanted something that worked completely inside of Neovim and made
170+
things look slightly "nicer".
171+
172+
The closest one I found to this was headlines.nvim
173+
<https://github.com/lukas-reineke/headlines.nvim>, which is an awesome plugin
174+
that I took several ideas from. However it just didn’t have quite what I was
175+
looking for. In particular I wanted something that would disappear completely
176+
when editing a file and quickly render some style when viewing the file. Hence
177+
this plugin.
178+
179+
180+
==============================================================================
181+
8. Related Projects *render-markdown-related-projects*
182+
183+
- headlines.nvim <https://github.com/lukas-reineke/headlines.nvim> - Same high level
184+
idea different features
185+
- markdown-preview.nvim <https://github.com/iamcco/markdown-preview.nvim> - Uses browser
186+
- vim-markdown-composer <https://github.com/euclio/vim-markdown-composer> - Uses browser
187+
188+
==============================================================================
189+
9. Links *render-markdown-links*
190+
191+
1. *Demo*: demo/demo.gif
192+
193+
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
194+
195+
vim:tw=78:ts=8:noet:ft=help:norl:

‎justfile

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,11 @@ demo zoom=default_zoom:
1111
--font-family "JetBrainsMono NFM" \
1212
--last-frame-duration 1
1313
rm demo.cast
14+
15+
docgen:
16+
# https://github.com/kdheepak/panvimdoc
17+
# https://pandoc.org/
18+
../../open-source/panvimdoc/panvimdoc.sh \
19+
--project-name render-markdown \
20+
--input-file README.md \
21+
--vim-version 0.9.5

0 commit comments

Comments
 (0)