Add firstLineBlank option

Closes GH-1.

Author: wooorm

index.d.ts

@@ -1,5 +1,14 @@
 export {gfmFootnoteFromMarkdown, gfmFootnoteToMarkdown} from './lib/index.js'
 
+export interface ToMarkdownOptions {
+  // To do: next major: change default.
+  /**
+   * Use a blank line for the first line of footnote definitions
+   * (`boolean`, default: `false`).
+   */
+  firstLineBlank?: boolean | null | undefined
+}
+
 declare module 'mdast-util-to-markdown' {
   interface ConstructNameMap {
     /**

lib/index.js

@@ -4,6 +4,7 @@
  *   Extension as FromMarkdownExtension,
  *   Handle as FromMarkdownHandle
  * } from 'mdast-util-from-markdown'
+ * @import {ToMarkdownOptions} from 'mdast-util-gfm-footnote'
  * @import {
  *   Handle as ToMarkdownHandle,
  *   Map,
@@ -96,31 +97,6 @@ function exitFootnoteDefinition(token) {
   this.exit(token)
 }
 
-/**
- * @type {ToMarkdownHandle}
- * @param {FootnoteDefinition} node
- */
-function footnoteDefinition(node, _, state, info) {
-  const tracker = state.createTracker(info)
-  let value = tracker.move('[^')
-  const exit = state.enter('footnoteDefinition')
-  const subexit = state.enter('label')
-  value += tracker.move(
-    state.safe(state.associationId(node), {before: value, after: ']'})
-  )
-  subexit()
-  value += tracker.move(
-    ']:' + (node.children && node.children.length > 0 ? ' ' : '')
-  )
-  tracker.shift(4)
-  value += tracker.move(
-    state.indentLines(state.containerFlow(node, tracker.current()), map)
-  )
-  exit()
-
-  return value
-}
-
 /** @type {ToMarkdownHandle} */
 function footnoteReferencePeek() {
   return '['
@@ -172,22 +148,65 @@ export function gfmFootnoteFromMarkdown() {
  * Create an extension for `mdast-util-to-markdown` to enable GFM footnotes
  * in markdown.
  *
+ * @param {ToMarkdownOptions | null | undefined} [options]
+ *   Configuration (optional).
  * @returns {ToMarkdownExtension}
  *   Extension for `mdast-util-to-markdown`.
  */
-export function gfmFootnoteToMarkdown() {
+export function gfmFootnoteToMarkdown(options) {
+  // To do: next major: change default.
+  let firstLineBlank = false
+
+  if (options && options.firstLineBlank) {
+    firstLineBlank = true
+  }
+
   return {
     handlers: {footnoteDefinition, footnoteReference},
     // This is on by default already.
     unsafe: [{character: '[', inConstruct: ['label', 'phrasing', 'reference']}]
   }
+
+  /**
+   * @type {ToMarkdownHandle}
+   * @param {FootnoteDefinition} node
+   */
+  function footnoteDefinition(node, _, state, info) {
+    const tracker = state.createTracker(info)
+    let value = tracker.move('[^')
+    const exit = state.enter('footnoteDefinition')
+    const subexit = state.enter('label')
+    value += tracker.move(
+      state.safe(state.associationId(node), {before: value, after: ']'})
+    )
+    subexit()
+
+    value += tracker.move(']:')
+
+    if (node.children && node.children.length > 0) {
+      tracker.shift(4)
+
+      value += tracker.move(
+        (firstLineBlank ? '\n' : ' ') +
+          state.indentLines(
+            state.containerFlow(node, tracker.current()),
+            firstLineBlank ? mapAll : mapExceptFirst
+          )
+      )
+    }
+
+    exit()
+
+    return value
+  }
 }
 
 /** @type {Map} */
-function map(line, index, blank) {
-  if (index === 0) {
-    return line
-  }
+function mapExceptFirst(line, index, blank) {
+  return index === 0 ? line : mapAll(line, index, blank)
+}
 
+/** @type {Map} */
+function mapAll(line, index, blank) {
   return (blank ? '' : '    ') + line
 }

readme.md

@@ -18,7 +18,8 @@
 * [Use](#use)
 * [API](#api)
   * [`gfmFootnoteFromMarkdown()`](#gfmfootnotefrommarkdown)
-  * [`gfmFootnoteToMarkdown()`](#gfmfootnotetomarkdown)
+  * [`gfmFootnoteToMarkdown(options?)`](#gfmfootnotetomarkdownoptions)
+  * [`ToMarkdownOptions`](#tomarkdownoptions)
 * [HTML](#html)
 * [Syntax](#syntax)
 * [Syntax tree](#syntax-tree)
@@ -126,7 +127,9 @@ const tree = fromMarkdown(value, {
 
 console.log(tree)
 
-const result = toMarkdown(tree, {extensions: [gfmFootnoteToMarkdown()]})
+const result = toMarkdown(tree, {
+  extensions: [gfmFootnoteToMarkdown({firstLineBlank: true})]
+})
 
 console.log(result)
 ```
@@ -187,10 +190,12 @@ console.log(result)
 ```markdown
 In the Solar System, Mercury[^mercury] and Venus[^venus] have very small tilts.
 
-[^mercury]: **Mercury** is the first planet from the Sun and the smallest
+[^mercury]:
+    **Mercury** is the first planet from the Sun and the smallest
     in the Solar System.
 
-[^venus]: **Venus** is the second planet from
+[^venus]:
+    **Venus** is the second planet from
     the Sun.
 ```
 
@@ -200,6 +205,7 @@ This package exports the identifiers
 [`gfmFootnoteFromMarkdown`][api-gfmfootnotefrommarkdown] and
 [`gfmFootnoteToMarkdown`][api-gfmfootnotetomarkdown].
 There is no default export.
+It exports the type [`ToMarkdownOptions`][api-to-markdown-options].
 
 ### `gfmFootnoteFromMarkdown()`
 
@@ -212,17 +218,31 @@ to enable GFM footnotes in markdown.
 Extension for `mdast-util-from-markdown`
 ([`FromMarkdownExtension`][frommarkdownextension]).
 
-### `gfmFootnoteToMarkdown()`
+### `gfmFootnoteToMarkdown(options?)`
 
 Create an extension for
 [`mdast-util-to-markdown`][mdast-util-to-markdown]
 to enable GFM footnotes in markdown.
 
+###### Parameters
+
+* `options` ([`ToMarkdownOptions`][api-to-markdown-options], optional)
+  — configuration
+
 ###### Returns
 
 Extension for `mdast-util-to-markdown`
 ([`ToMarkdownExtension`][tomarkdownextension]).
 
+### `ToMarkdownOptions`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `firstLineBlank` (`boolean`, default: `false`)
+  — use a blank line for the first line of footnote definitions
+
 ## HTML
 
 This utility does not handle how markdown is turned to HTML.
@@ -381,7 +401,9 @@ abide by its terms.
 
 [api-gfmfootnotefrommarkdown]: #gfmfootnotefrommarkdown
 
-[api-gfmfootnotetomarkdown]: #gfmfootnotetomarkdown
+[api-gfmfootnotetomarkdown]: #gfmfootnotetomarkdownoptions
+
+[api-to-markdown-options]: #tomarkdownoptions
 
 [author]: https://wooorm.com
 

test.js

@@ -361,4 +361,37 @@ test('gfmFootnoteToMarkdown', async function (t) {
       )
     }
   )
+
+  await t.test('should support `firstLineBlank`', async function () {
+    assert.deepEqual(
+      toMarkdown(
+        {
+          type: 'footnoteDefinition',
+          identifier: 'a',
+          children: [
+            {type: 'paragraph', children: [{type: 'text', value: 'b'}]}
+          ]
+        },
+        {extensions: [gfmFootnoteToMarkdown({firstLineBlank: true})]}
+      ),
+      '[^a]:\n    b\n'
+    )
+  })
+
+  await t.test(
+    'should support `firstLineBlank` w/o children',
+    async function () {
+      assert.deepEqual(
+        toMarkdown(
+          {
+            type: 'footnoteDefinition',
+            identifier: 'a',
+            children: []
+          },
+          {extensions: [gfmFootnoteToMarkdown({firstLineBlank: true})]}
+        ),
+        '[^a]:\n'
+      )
+    }
+  )
 })