Reading a note

A notebook is read far more often than it is written. This page covers what a note does when you are reading it: following links, seeing where they go before you commit to them, opening a linked file, reading a PDF beside the note you are writing from it, and locking a note so that reading it cannot change it.

Opening a link

Click it. Links always open in a new tab, from the preview and from Rich view alike — the alternative is navigating away from a note that may hold writing which has not reached GitHub yet.

Alt-click is how you edit a link’s text in Rich view. It takes the modifier rather than the plain click because a link gets followed a great many times for every time its wording is changed — and in Source view the markdown is plain text you edit like any other.

Links to your own notes

A [[wikilink]] opens the note it names in a tab here, rather than in the browser. If no note of that name exists yet, clicking it writes one — linking ahead of yourself is how an outline gets built.

The hover card

Rest the pointer on a link for a moment and a small card appears with:

• the host — github.com, builtwith.com;
• the page’s own title;
• its own one-line description of itself, when it publishes one;
• the picture it offers of itself, when it has one;
• the full address, so you can see where you are actually going.

The card stays while the pointer is on it, so the address can be selected and copied. Escape closes it, and it closes by itself when the note scrolls.

A page that cannot be read — offline, blocked, an address inside a private network — still gets a card with its host and address. Addresses that resolve inside a private network are refused outright, which is why a link to something on your own machine or an intranet shows no title.

Reading a linked file

A [[repo:path/to/file]] link names a file in the repository rather than a note. Clicking one opens the file for reading without leaving the note:

• Markdown renders as markdown; everything else is shown as highlighted source.
• Images are shown as images.
• It opens at the revision the link pinned — @a1b2c3d — not at whatever the branch holds now. That is the point: a link that reports itself stale has to be able to show you what the note was actually written about.
• Open on GitHub is there for the rest — history, blame, editing.

The file names listed under Freshness in the properties panel open the same viewer.

Reading a PDF

ForkLeaf opens PDFs. Not as an attachment or a download — as a document beside the note you are writing from it, with the passages you quote linked back to the exact words on the page.

Four ways in

• The document button beside New Note in the sidebar, or Open a PDF… in the command palette (⌘K). Chromium browsers only — Firefox and Safari have no file picker ForkLeaf can use, which is why the next one exists.
• Drag one onto the window. Works in every browser.
• Click one in the sidebar. A PDF committed to your repository sits in the file tree beside your notes, and clicking it opens the reader rather than trying to edit it as text.
• Click a link to one in a note. An ordinary markdown link — [the paper](papers/attention.pdf) — opens the reader instead of navigating away from what you were writing.

Install ForkLeaf and .pdf joins .md in your operating system’s Open with list. ForkLeaf does not make itself your default PDF viewer and should not; that is your setting to make.

A tab, or beside the note

A PDF from your repository opens in a tab of its own, because a typeset page squeezed into half a laptop screen is not a width anybody reads a book at. That tab is a real link: bookmark it, open two of them side by side, or send it to somebody with access to the same repository and it opens on the same page.

When you are writing from a document rather than reading it, you want both at once. Two ways to get that:

• Open beside this note from the right-click menu on a PDF in the sidebar — just this once.
• Open PDFs beside the note instead in the command palette — from now on. The setting is remembered on this device, and Open in tab in the reader’s own header gives the room back when you want it.

The reader tab has no note to write into, so selecting a passage there offers Copy quotation instead: the same markdown the panel would have inserted, ready to paste into whichever note you want it in.

Keeping a PDF in your notebook

A PDF dragged in from your desktop can be read and quoted, but the quotation cannot link back to it — there is no path in your repository for a link to point at, so it gets a plain attribution instead. Save to notebook in the reader’s header commits the file into a papers/ folder beside the note you are reading it with, exactly as an image is filed beside the note that uses it. Every citation of it becomes a real link from then on.

ForkLeaf can read a document far larger than it can save one. A commit from the browser carries the file as text inside a request the host caps at a few megabytes, so anything over 3 MB can be read all day and cannot be committed — the reader says so rather than letting the save fail.

In the reader

Quoting into a note

Select a passage and the reader offers Quote into note. What lands in the note is a blockquote and a link, and nothing else:

> The key result is that latency fell by half.
>
> — [On Attention, p. 12](papers/attention.pdf#page=12&q=…)

That is a plain markdown link. It renders on github.com, it opens page 12 in Acrobat, in Preview and in your browser’s own viewer — #page= is the parameter every PDF reader has understood since 2003 — and in ForkLeaf it does something more.

Why the link carries the sentence

A citation that records only a page number is wrong the moment the document changes. Add a figure to page 4 of a paper and every reference to page 12 now points at page 13 — silently, because the link still opens.

So a ForkLeaf citation records the words, with the page number kept only as a hint about where to start looking. Clicking one searches the document for that passage, uses the text either side of it to tell two occurrences apart, and opens the page it is actually on with the sentence highlighted. If the passage has genuinely gone, you are told — rather than being shown whatever happens to be on page 12 now.

The q=, pre= and suf= parameters are how that is carried, and any tool that does not understand them ignores them and still lands on the right page.

Locking a note

A reference note is one you read far more often than you write. Reading it means clicking around in it, which leaves the cursor somewhere in the text — and from there a stray keystroke is an edit that saves itself, commits itself, and is found weeks later as a lone character in the middle of a paragraph.

The padlock in the editor header locks the note on screen. ⌘⇧L does the same, and so does Lock this note against editing in the command palette.

What a lock stops

• Typing, in all three views.
• The formatting bar, which disappears rather than sitting there greyed out.
• The / menu, and every toolbar action that would write to the note.
• Pasting or dropping an image.
• Undo and redo.
• The properties panel — title, tags and custom fields are all disabled.
• Adding a linked file or a captured source, which say so rather than doing nothing.
• The automatic repair pass that fixes image links when a note opens.

What it does not stop

• Reading, selecting and copying — the whole point. Links still open, diagrams still render.
• Changes arriving from GitHub. A colleague’s commit still lands: the lock is about your hands, not about freezing the file.
• Renaming or deleting the note. Both are deliberate acts behind their own confirmation, and a lock carries across a rename rather than falling off.
• Editing the same note somewhere else. The lock is remembered on this device only.