Skip to content
This repository was archived by the owner on Aug 9, 2023. It is now read-only.

Commit 108b8fc

Browse files
wooormwooorm
committed
Mark mdast-util-footnote as legacy
1 parent 3518cc4 commit 108b8fc

File tree

1 file changed

+14
-265
lines changed

1 file changed

+14
-265
lines changed

‎readme.md

Lines changed: 14 additions & 265 deletions
Original file line numberDiff line numberDiff line change
@@ -1,277 +1,26 @@
11
# mdast-util-footnote
22

3-
[![Build][build-badge]][build]
4-
[![Coverage][coverage-badge]][coverage]
5-
[![Downloads][downloads-badge]][downloads]
6-
[![Size][size-badge]][size]
7-
[![Sponsors][sponsors-badge]][collective]
8-
[![Backers][backers-badge]][collective]
9-
[![Chat][chat-badge]][chat]
10-
11-
Extension for [`mdast-util-from-markdown`][from-markdown] and/or
12-
[`mdast-util-to-markdown`][to-markdown] to support footnotes in **[mdast][]**.
13-
When parsing (`from-markdown`), must be combined with
14-
[`micromark-extension-footnote`][extension].
15-
16-
## When to use this
17-
18-
Use this if you’re dealing with the AST manually.
19-
It might be better to use [`remark-footnotes`][remark-footnotes] with
20-
**[remark][]**, which includes this but provides a nicer interface and makes it
21-
easier to combine with hundreds of plugins.
22-
23-
## Install
24-
25-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
26-
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
27-
28-
[npm][]:
29-
30-
```sh
31-
npm install mdast-util-footnote
32-
```
33-
34-
## Use
35-
36-
Say we have the following file, `example.md`:
37-
38-
```markdown
39-
Here is a footnote call,[^1] and another.[^longnote]
40-
41-
[^1]: Here is the footnote.
42-
43-
[^longnote]: Here’s one with multiple blocks.
44-
45-
Subsequent paragraphs are indented to show that they
46-
belong to the previous footnote.
47-
48-
{ some.code }
49-
50-
The whole paragraph can be indented, or just the first
51-
line. In this way, multi-paragraph footnotes work like
52-
multi-paragraph list items.
53-
54-
This paragraph won’t be part of the note, because it
55-
isn’t indented.
56-
57-
Here is an inline note.^[Inlines notes are easier to write, since
58-
you don’t have to pick an identifier and move down to type the
59-
note.]
60-
```
61-
62-
And our module, `example.js`, looks as follows:
63-
64-
```js
65-
import fs from 'node:fs'
66-
import {fromMarkdown} from 'mdast-util-from-markdown'
67-
import {toMarkdown} from 'mdast-util-to-markdown'
68-
import {footnote} from 'micromark-extension-footnote'
69-
import {footnoteFromMarkdown, footnoteToMarkdown} from 'mdast-util-footnote'
70-
71-
const doc = fs.readFileSync('example.md')
72-
73-
const tree = fromMarkdown(doc, {
74-
extensions: [footnote({inlineNotes: true})],
75-
mdastExtensions: [footnoteFromMarkdown]
76-
})
77-
78-
console.log(tree)
79-
80-
const out = toMarkdown(tree, {extensions: [footnoteToMarkdown]})
81-
82-
console.log(out)
83-
```
84-
85-
Now, running `node example` yields:
86-
87-
```js
88-
{
89-
type: 'root',
90-
children: [
91-
{
92-
type: 'paragraph',
93-
children: [
94-
{type: 'text', value: 'Here is a footnote call,'},
95-
{type: 'footnoteReference', identifier: '1', label: '1'},
96-
{type: 'text', value: ' and another.'},
97-
{type: 'footnoteReference', identifier: 'longnote', label: 'longnote'}
98-
]
99-
},
100-
{
101-
type: 'footnoteDefinition',
102-
identifier: '1',
103-
label: '1',
104-
children: [
105-
{
106-
type: 'paragraph',
107-
children: [{type: 'text', value: 'Here is the footnote.'}]
108-
}
109-
]
110-
},
111-
{
112-
type: 'footnoteDefinition',
113-
identifier: 'longnote',
114-
label: 'longnote',
115-
children: [
116-
{
117-
type: 'paragraph',
118-
children: [{type: 'text', value: 'Here’s one with multiple blocks.'}]
119-
},
120-
{
121-
type: 'paragraph',
122-
children: [
123-
{type: 'text', value: 'Subsequent paragraphs are indented to show that they\nbelong to the previous footnote.'}
124-
]
125-
},
126-
{type: 'code', value: '{ some.code }'},
127-
{
128-
type: 'paragraph',
129-
children: [
130-
{type: 'text', value: 'The whole paragraph can be indented, or just the first\nline. In this way, multi-paragraph footnotes work like\nmulti-paragraph list items.'}
131-
]
132-
}
133-
]
134-
},
135-
{
136-
type: 'paragraph',
137-
children: [
138-
{type: 'text', value: 'This paragraph won’t be part of the note, because it\nisn’t indented.'}
139-
]
140-
},
141-
{
142-
type: 'paragraph',
143-
children: [
144-
{type: 'text', value: 'Here is an inline note.'},
145-
{
146-
type: 'footnote',
147-
children: [
148-
{type: 'text', value: 'Inlines notes are easier to write, since\nyou don’t have to pick an identifier and move down to type the\nnote.'}
149-
]
150-
}
151-
]
152-
}
153-
]
154-
}
155-
```
156-
157-
```markdown
158-
Here is a footnote call,[^1] and another.[^longnote]
159-
160-
[^1]: Here is the footnote.
161-
162-
[^longnote]: Here’s one with multiple blocks.
163-
164-
Subsequent paragraphs are indented to show that they
165-
belong to the previous footnote.
166-
167-
{ some.code }
168-
169-
The whole paragraph can be indented, or just the first
170-
line. In this way, multi-paragraph footnotes work like
171-
multi-paragraph list items.
172-
173-
This paragraph won’t be part of the note, because it
174-
isn’t indented.
175-
176-
Here is an inline note.^[Inlines notes are easier to write, since
177-
you don’t have to pick an identifier and move down to type the
178-
note.]
179-
```
180-
181-
## API
182-
183-
This package exports the following identifier: `footnoteFromMarkdown`,
184-
`footnoteToMarkdown`.
185-
There is no default export.
186-
187-
### `footnoteFromMarkdown`
188-
189-
### `footnoteToMarkdown`
190-
191-
Support footnotes.
192-
These exports are extensions, respectively for
193-
[`mdast-util-from-markdown`][from-markdown] and
194-
[`mdast-util-to-markdown`][to-markdown].
195-
196-
## Related
197-
198-
* [`remarkjs/remark`][remark]
199-
— markdown processor powered by plugins
200-
* [`remarkjs/remark-footnotes`][remark-footnotes]
201-
— remark plugin to support footnotes
202-
* [`micromark/micromark`][micromark]
203-
— the smallest commonmark-compliant markdown parser that exists
204-
* [`micromark/micromark-extension-footnote`][extension]
205-
— micromark extension to parse footnotes
206-
* [`syntax-tree/mdast-util-from-markdown`][from-markdown]
207-
— mdast parser using `micromark` to create mdast from markdown
208-
* [`syntax-tree/mdast-util-to-markdown`][to-markdown]
209-
— mdast serializer to create markdown from mdast
210-
211-
## Contribute
212-
213-
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
214-
started.
215-
See [`support.md`][support] for ways to get help.
216-
217-
This project has a [code of conduct][coc].
218-
By interacting with this repository, organization, or community you agree to
219-
abide by its terms.
3+
**Stability: Legacy**.
4+
This package is no longer recommended for use.
5+
It’s still covered by semantic-versioning guarantees and not yet deprecated,
6+
but use of this package should be avoided.
7+
Please use [`mdast-util-gfm-footnote`][gfm-footnote] (or
8+
[`mdast-util-gfm`][gfm], which includes it and all of GFM) instead.
9+
Those packages match how footnotes work on github.com, which is more likely
10+
to match the expectations of your authors.
11+
12+
Legacy [documentation for this
13+
package](https://github.com/syntax-tree/mdast-util-footnote/tree/13c67e0)
14+
is still available in Git.
22015

22116
## License
22217

22318
[MIT][license] © [Titus Wormer][author]
22419

225-
<!-- Definitions -->
226-
227-
[build-badge]: https://github.com/syntax-tree/mdast-util-footnote/workflows/main/badge.svg
228-
229-
[build]: https://github.com/syntax-tree/mdast-util-footnote/actions
230-
231-
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-footnote.svg
232-
233-
[coverage]: https://codecov.io/github/syntax-tree/mdast-util-footnote
234-
235-
[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-footnote.svg
236-
237-
[downloads]: https://www.npmjs.com/package/mdast-util-footnote
238-
239-
[size-badge]: https://img.shields.io/bundlephobia/minzip/mdast-util-footnote.svg
240-
241-
[size]: https://bundlephobia.com/result?p=mdast-util-footnote
242-
243-
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
244-
245-
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
246-
247-
[collective]: https://opencollective.com/unified
248-
249-
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
250-
251-
[chat]: https://github.com/syntax-tree/unist/discussions
252-
253-
[npm]: https://docs.npmjs.com/cli/install
254-
25520
[license]: license
25621

25722
[author]: https://wooorm.com
25823

259-
[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
260-
261-
[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
262-
263-
[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
264-
265-
[mdast]: https://github.com/syntax-tree/mdast
266-
267-
[remark]: https://github.com/remarkjs/remark
268-
269-
[remark-footnotes]: https://github.com/remarkjs/remark-footnotes
270-
271-
[from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
272-
273-
[to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
274-
275-
[micromark]: https://github.com/micromark/micromark
24+
[gfm]: https://github.com/syntax-tree/mdast-util-gfm
27625

277-
[extension]: https://github.com/micromark/micromark-extension-footnote
26+
[gfm-footnote]: https://github.com/syntax-tree/mdast-util-gfm-footnote

0 commit comments

Comments
 (0)