alphagov/govspeak — pull request #4 by floehopper (2012-07-06 14:57:09+00:00)
Title: Automatically add rel='external' attribute where appropriate.

This seems to be a more robust and editor-friendly approach compared to
the current syntax which requires the standard markdown link syntax to
be surrounded by an 'x' character at either end.

I started work on this in response to a bug raised in whitehall where it
was noticed [1,2] that a link marked as external using the 'x' syntax with
text before or after it, would not be processed correctly i.e. the 'x'
characters are left behind in the HTML output and the link does not have
the rel='external' attribute set.

It's not completely ideal, because I've overriden the
`Kramdown::Parser::Kramdown#add_link` method, but this is a public
method and the tests I've added should catch any changes to the Kramdown
API.

The reason I feel it's more robust is that we can make use of Kramdown's
own existing parsing of the markdown link syntax rather than adding to
the complexity of the regular expression craziness that is already
getting out of hand - see the FIXME comment added by @bradleywright and
his commit note for 5a8f8a0c58bd44778a78b7b99a5d1fbbe3103c68. I think we
could get ourselves in a real mess trying to use regular expressions to
do all this pre-processing. Although we're not actually trying to parse
HTML, I'm pretty sure markdown is not a "regular" language either and so
most of the same arguments presented in [3] are relevant.

The reason I feel it's more user-friendly is that the user (content
editor) does not have to worry about whether or not the link is
external. Also, because it is automatic, it should be less error prone.

I have confirmed with Neil Williams that links between propositions
within www.gov.uk should never be regarded as "external", however I've
made provision for allowing different and/or multiple
"document_domains". We need this in the whitehall project, because
we re-write admin URLs (on one domain) to public-facing URLs (on another
domain).

This change should be backwardly compatible with the 'x' style syntax
i.e. it should still be possible to manually force a link to be made
"external" using the 'x' syntax, but I would hope we could remove this
in time if we run a batch job to remove such links from content across
all projects using the govspeak library.

[1] https://www.preview.alphagov.co.uk/specialist/shiny
[2] https://www.pivotaltracker.com/story/show/32105039
[3]
http://stackoverflow.com/questions/1732348/regex-match-open-tags-except-xhtml-self-contained-tags/1732454#1732454