Adding a link by hand

Paste an address into the composer and Issue Mint reads the page, so the title and a description arrive filled in and the part that matters, your comment on the link, is the part you write.

What happens when you paste an address

Issue Mint fetches the page and fills in the fields around it. The title arrives, your comment field starts as the page’s own description, and the address is replaced with the page’s canonical version of itself where it declares one, which quietly removes the campaign tags a link picks up on its way to you.

The form itself sits behind the Add link button on every section in the composer, and it has three fields: the link, the title and your comment. Nothing is saved by the look-up. Pressing Add link is what saves.

When the look-up runs

The look-up runs on its own the first time you leave the link field, and the Fetch button beside the field runs it again whenever you want.

Once it has run once, leaving the field does not trigger it again, so editing a title by hand and clicking away will not have your work overwritten. Pasting a different address and pressing Fetch is the way to look something else up.

What the look-up reads

Three things off the page: a title, a description and the page’s preferred address.

Issue Mint prefers what the publisher chose for sharing, so the title comes from the Open Graph title, then a Twitter card title, then the page’s own title tag, and the description comes from the Open Graph description, then the meta description, then a Twitter card description. Each value is trimmed to five hundred characters, which is longer than any of the three fields needs.

It reads markup and nothing else. A PDF, an image or a file download has no metadata to read, so the fields come back empty and you fill them in. It also reads the page’s social image, and nothing uses it: an ordinary link in an issue does not carry a picture, and the only image in an issue is the artwork on a sponsored item, which you upload yourself.

The limits the look-up works to

Issue Mint waits 5 seconds for a page, reads the first 1 MB of it, and follows up to 3 redirects, checking each hop before taking it.

Only http and https addresses are read, and only on the ordinary web ports. An address that resolves to a private or reserved network is refused outright, so a page on your own machine, your office intranet or a staging server nobody outside can reach cannot be looked up from here, however valid the address is. Every fetch identifies itself in the publisher’s logs as IssueMintBot/1.0, with a link to a page explaining what it wanted.

When it comes back with nothing

You add the link anyway. A page that cannot be read is not an error that stops you: the message says so, the fields stay editable, and a link with a title you typed yourself is identical in the issue to one that arrived prefilled.

That covers a fair range of ordinary cases, including a site that blocks anything that is not a browser, a page that takes longer than the timeout to answer, and a slug that turns out to be a redirect chain three hops long. If you can see the page in your own browser, the Chrome extension reads it from there instead.

How long each field can be

An address can be up to 2,048 characters, a title up to 250, and your comment up to 5,000.

Your comment takes markdown, so a link, a bit of emphasis or a blockquote of the line you are reacting to all work. The title is one line and is the reader’s whole introduction to the link, so it is worth rewriting when the publisher’s own title is a piece of search-engine housekeeping rather than a description.

Where the link lands

At the end of the section whose Add link button you pressed, which is what adding links to an issue covers in full.

Nothing is fixed after that. Links drag between sections and up and down within one, a section with nothing in it does not appear in the issue at all, and the address, title and comment can all be edited on the link afterwards.