Using citation-style links and footnotes in Markdown

Matrix homepage recommendation

Matrix is ​​a minority writing community. We advocate sharing real product experience, experience and thinking with practical value. From time to time, we will select the highest-quality articles from Matrix to show the most authentic experiences and opinions from users.
The article represents the author’s personal point of view, and the minority only makes minor changes to the title and layout.

citation link

As we all know, links in Markdown are written like this:

 This is [an example]( "Title") inline link. [This link]( has no title attribute.

This widely used way of writing links is called an inline link. In fact, there is another less commonly used way of writing links in Markdown, that is, reference-style links. Its form is as follows:

 This is [an example] [id] reference-style link. [id]: "Optional Title Here"

It can be found that the reference link uses two square brackets in the text. The first square bracket wraps the text part of the hyperlink, which is [an example] here, followed by an optional space , and then use the second square brackets to wrap the identifier of the link, which is represented by [id] here.

In the link section below, the identifier [id] of the link appears first, followed by a colon : , followed by one or more spaces (or the Tab key), then the URL of the link, and finally an optional The title of the link, whose format is consistent with the title of the inline link, wrapped in parentheses () , double quotes " or single quotes ' . In addition, the link identifier can also be omitted for quoted links, that is, the second square bracket is omitted The content in this link is called an implicit link (implicit link), and its writing method is as follows:

 [Google][] [Google]:

What are the benefits of citation links over inline links? John Gruber gave an explanation when he introduced the basic grammar of Markdown:

The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable.

The point of citation links is not that they are easier to write, the point is that using citation links can greatly improve the readability of Markdown source files.

Indeed, when there are a large number of links in Markdown source files, and these links are very lengthy and unattractive, inline links will not only significantly reduce the readability of source files, but even interfere with our writing ideas, while reference links will This problem can be largely avoided. In addition, during the writing process, we often don’t want to interrupt the writing process to search for links on the Internet. In this case, we can first place a reference link placeholder to facilitate subsequent supplements. It doesn’t matter if you forget to fill in the link, the Markdown grammar checker will mark it in the wrong form and remind us to modify it.

A Markdown file, comparing the effects of using inline links and citation links respectively, it is obvious that the citation links on the right are more readable A Markdown file, comparing the effect of using inline links and reference links respectively, it is obvious that the reference links on the right are more readable

Related reading: Pick your markdown – entry and advanced grammar checker

Insert Quoted Links Using Keyboard Maestro

A few days ago, when the minority editor @PlatyHsu used reference links (he called them “split links”) in the “wall crack recommendation” in the member group, I commented that “it’s a bit troublesome to add a link identifier manually”. But then I realized that compared to the convenience brought by citation links, this trouble is still acceptable, and what I want to do is to make the process of writing citation links easier. To do this, I made a Keyboard Maestro action ( ⬇ Click to download ) to help me quickly insert citation-style links when writing in Markdown.

Keyboard Maestro actions to quickly insert quote-like links Keyboard Maestro Action to Quickly Insert Quoted Links

The main principle of this Keyboard Maestro action is to generate a random link identifier (3 digits are set here, UUID consists of uppercase English letters and Arabic numerals) to avoid possible duplication during manual editing. The identifier and URL are then inserted into the corresponding positions in the format of a referenced link.

The method of use is very simple, first copy the URL of the link to the clipboard, then move the cursor in the Markdown file to select the text to insert the link, and then press the shortcut key ⌥ + ⇧ + K (you can also modify it to other shortcut keys) , the link in the clipboard will be automatically inserted as a quoted link. It should be noted that if you use a sentence-for-line writing method, you may need to move the inserted link text up and down a few lines; if you use Vim in VS Code , please do not perform this action in Normal Mode, but need First press i or a to enter Insert Mode, and then perform this Keyboard Maestro action.

Quickly Insert Quoted Links Using Keyboard Maestro Actions Quickly Insert Quoted Links Using Keyboard Maestro Actions

Using citation links in Pandoc’s Markdown

If you need to convert existing inline links in Markdown to reference links, you can use Pandoc ‘s --reference-links option , for example:

 pandoc --reference-links --reference-location=block -o

In this line of command, --reference-links specifies the use of reference links instead of the default inline links, --reference-location=block indicates that the location of reference links is block , that is, placed below each paragraph, and the other two The two options are section (placed at the end of the current section) and document (placed at the end of the document, the default option). The input file is and the output file is .

It is worth mentioning that Pandoc also provides an extension shortcut_reference_links , which supports omitting the second square bracket of the reference link, that is, you can shorten the reference link in Markdown like this (when converted to markdown , this is a default open option):

 See [my website]. [my website]:

In addition, if you are used to adding a space between the two square brackets of reference links, that is, [foo] [bar] , you can enable the spaced_reference_links extension when converting with Pandoc.

Related reading: Pandoc from entry to mastery, you can also learn this text conversion tool

quoted footnote

Although standard Markdown does not support footnotes, many Markdown variants do. In general, most Markdown dialects and editors support both inline and quoted footnotes, with the latter being more commonly used:

 Here is a footnote reference,[^1] and another.[^longnote] [^1]: Here is the footnote. [^longnote]: Here's one with multiple blocks.

Writing with relatively few inline footnotes:

 Here is an inline note.^[Inline notes are easier to write, since you don't have to pick an identifier and move down to type the note.]

It is easy to find that footnotes are written very similarly to links. Inline footnotes are written concisely, and quoted footnotes are more readable, but need to manually add an identifier when writing. In order to avoid possible conflicts in identifiers caused by manual editing, we again use the Keyboard Maestro action to randomly generate identifiers ( ⬇ Click to download ).

Keyboard Maestro action for inserting quoted footnotes Keyboard Maestro action for inserting quoted footnotes

The idea of ​​this Keyboard Maestro action is similar to the action of inserting a reference link, so I won’t repeat it here. It is also very simple to use, you only need to position the cursor where you want to insert a footnote, and then press the shortcut key ⌥ + ⇧ + J , it will automatically insert the footnote identifier, and position the cursor to fill in the content of the footnote Location.

Insert quoted footnotes using Keyboard Maestro actions Insert quoted footnotes using Keyboard Maestro actions


@PlatyHsu said: “There are many people who can write Markdown, but there are very few people who can write Markdown well.” Indeed, although Markdown is easy to use, it still requires continuous learning to write it well. Using reference links and footnotes in Markdown can be regarded as a writing habit worth learning, because it can greatly improve the readability of your Markdown documents, and is more conducive to subsequent editing and revision. This article introduces these two “quoted writing methods” and how to use Keyboard Maestro or Pandoc to quickly insert or convert quoted links and footnotes to improve writing efficiency. If you have a better method or want to add content, please share it in the comment area.

> Download the Minority 2.0 client , follow the Minority official account, and unlock a new reading experience 📰

> Practical and easy-to-use genuine software , presented to you by the minority 🚀

This article is transferred from:
This site is only for collection, and the copyright belongs to the original author.