Linking effectively

View source | View history | Atom feed for this file
Last substantive revision date
2016-07-12
Last modification date
2022-05-03
Generated on
2024-04-30

Some places to look:

Things to talk about:

Links often emphasize text on a page (in many browsers links are underlined and colored differently). So consider the sentence “Stopping X shouldn’t be a high priority.” It would be natural to hyperlink this to something that argues this point like so (where square brackets denote the part of the sentence that is linked):

Stopping X [shouldn't be a high priority].

This gets the emphasis right. But now what if we want the sentence to read instead “I don’t think stopping X should be a high priority.”?

Consider the straightforward hyperlink translation:

I don't think stopping X [should be a high priority].

Someone quickly scanning the sentence might now accidentally interpret that stopping X should be a high priority! Instead we want something like the following:

I [don't think stopping X should be a high priority].

Or:

I don't think stopping X should be a [high priority].

Or:

I [don't think] stopping X should be a high priority.

The exact placement of the link depends on the emphasis one wants to give.

Compatibility with PDFs

A general rule is, you should always imagine how a page would look if you removed all the hyperlinks. So this means using words like “here” for linking should be discouraged.

Pandoc has -M links-as-notes:true, but, while this exposes all URLs in the document, it also messes up the footnote numbering in the sense that an HTML version will have footnotes that increase more slowly (and there is no one-to-one correspondence).

If the full citation is only needed so people can locate the material, one idea might be to include the citation information in the title text of the URL. In Pandoc markdown this is accomplished by

[link text](http://example.com "title text here")

One problem is that in PDFs, the title text is lost (though it might be possible to show them by writing an appropriate Pandoc filter).

Pandoc also provides a full citation filter through pandoc-citeproc, but I’m not sure this is worth it in most cases. Inline linking did something right by making it more intuitive and emphatic to click on things, and it would feel like returning to an inferior system to go back to academic citations. Of course, link rot is the major downside of inline links, but there are also others (like not having access to the full citation, so not being able to search for something using the citation information).

There is also the issue of including quotes from the destination. In academic citations (and also on Wikipedia), it’s possible to include quotes directly in footnotes, so that even if the destination disappears, the actually-relevant piece of information is safe.

See also the Markdown style guide from Google:

Titling your links as “link” or “here” tells the reader precisely nothing when quickly scanning your doc and is a waste of space:

See the syntax guide for more info: [link](syntax_guide.md).
Or, check out the style guide [here](style_guide.md).
DO NOT DO THIS.

Instead, write the sentence naturally, then go back and wrap the most appropriate phrase with the link:

See the [syntax guide](syntax_guide.md) for more info.
Or, check out the [style guide](style_guide.md).

Readability vs writability

One Markdown style guide says:

unaligned tables tables are easier to write, but aligned tables are more readable, and people read code much more often than they edit it.

Similarly, Markdown documents for websites such as this one are read much more often in rendered form than they are edited or read in source markup form (one would hope). This means it makes sense to sacrifice conveniences in the source markup when they make the output better (for instance using the Unicode thinspace between two consecutive quote marks, even if an ASCII space looks the same in a terminal).

However, given identical output, is it better to sacrifice readability of the source for easier input, or vice versa? Brandon Rhodes argues for the use of “semantic linefeeds”, i.e. breaking lines where it makes sense to do so semantically. He also cites Brian Kernighan saying the same thing way back in 1974. This of course sacrifices readability of the source to some extent, since lines will look jagged and will break at uneven points. It’s worth noting that Rhodes says:

I ask students whether or not the Sphinx text files in their project will be read by end-users. If not, then I encourage students to treat the files as private “source code” that they are free to format semantically.

That is, one question to ask is whether anyone else will read your input files, and if not, using “semantic linefeeds” seems like a fair way to go about editing.

Some related links:

Desiderata

See also