MojoPad

Transclusion and Panes

A wiki gets its power from reuse: write something once, see it everywhere it matters. MojoPad takes the page embed further — embed just a section, or just a single block, and open a second page beside the one you're writing. All of it live.

Embed a section

Add a heading's name after the page name and the embed shows just that section — the heading and everything under it, up to the next heading of the same level:

![[Project Plan#Milestones]]

Three ways to make one:

  • Type it — ![[Page#Heading]] on its own line, on any page that takes text: formatted, Markdown, or plain text.
  • Pick it — type / and choose Embed page; after you pick a page with headings, MojoPad offers the whole page or any single section.
  • Copy it from the outline — open the Outline (⌃⌘O), hover a heading, and click the ⧉ that appears. Paste on any page and it becomes the live embed.

Embedding on a plain-text page

Plain-text pages embed too — put ![[Page Name]] on a line of its own and it renders there like anywhere else, whole page or single section. A reader asked for exactly this: a plain-text page should be able to pull in another plain-text page, and there was no good reason it couldn't.

What is worth knowing is what the file holds. A plain-text page's whole promise is that the text is the text, so what is stored is the marker you typed — ![[Page Name]] — and never the borrowed words. Edit around it, close the page, open it in any other editor: the line is still five characters and a page name. The embed is a way of seeing the other page, not a copy of it, so the other page changing changes what you see here and nothing needs re-doing.

The marker has to be alone on its line. ![[Notes]] and more stays as written, on the same principle: a block that swallowed the words beside it would be taking liberties with a page whose point is that it doesn't.

And it travels. Export the page — HTML, PDF, Markdown, Word, ePub, a published site — and the embedded page comes with it as a quoted passage under its own name, the same as on any other page type. So a plain-text outline of a talk assembled out of ![[Section One]] markers goes out as the whole talk, not as a page of markers. The same is true of a pane beside it and of a card: what you see is the other page, wherever you are looking from.

Embed a single block

Any paragraph, heading, or list item can carry a small permanent name — a block id — and be embedded anywhere:

  1. Click into the paragraph you want to reference.
  2. Run Copy Block Link from the command palette (⇧⌘P).
  3. Paste. ![[Page#^ab12cd]] becomes a live embed of just that block.

On Markdown pages the id is plain text — a trailing marker like Some paragraph. ^ab12cd — so it travels with your notes and round-trips cleanly (the marker is hidden when the page renders). You can write your own memorable ids: end a line with ^budget and reference it as ![[Plans#^budget]].

An embed travels with the export

When you export a page — HTML, PDF, Markdown, Word, ePub, a published site — an embedded page comes with it, as a quoted passage under the name of the page it came from. So a manuscript assembled out of ![[Chapter One]] embeds exports as the whole manuscript, not as a page full of holes. Embeds nest three deep and never loop; a live database view names itself rather than pretending to be a table in a file that can't refresh.

Live, and connected

Section and block embeds are live views: edit the source and every embed shows the new content the next time it renders. Click an embed's title to jump to the source, right at that section. Embeds count as connections — they appear in Backlinks and on the Graph.

Panes: several pages side by side, each with its own tabs

Some work needs more than one page in view at once. Three cases panes are built for:

  • Writing an argument out of four papers. Your summary on the left, the studies it weighs standing in panes to its right, and a colored thread from each sentence to the paper it leans on. Every pane is a whole page: scroll it, search it, mark it, quote from it, or type in it.
  • Notes beside a draft. This week's plan beside last week's, a chapter beside its outline — both yours to change, each saving to its own page.
  • A source beside the page you are writing. A book or a PDF in one pane with its whole reader — zoom, find, marks, where you left off — while you write about it in the other.

Opening a page beside

There is one command for it: Open Beside. It opens a page in a new pane to the right of the pane you are in, and your caret stays where you were writing.

  • Right-click a link, or a page in any list — the Pages panel, search results, a database view, a tab — and choose Open Beside.
  • ⌥-click a page link.
  • Press ⌥⌘↩. With the caret in a link, or just after one you have typed, that page opens beside and your caret stays in the sentence — the quickest way to bring up a source while you write about it. With the caret anywhere else, it asks which page, as View ▸ Open Beside… does. In a dialog, a list or a board card being written in, the key is left to them. You can give it another key in Settings ▸ Shortcuts.
  • View ▸ Open Beside… (also in the command palette) asks which page, all from the keyboard. Type a name nothing matches and it offers Write in a new page…: the page it makes opens on the left and the threads start from it, because the page being written goes where writing goes, and reading runs left to right.
  • If you would like every link to do this, choose Open Beside the page you are in under Settings ▸ Links & Pages. A plain click on a link then adds a pane, in every pane.

Earlier versions had four names for this — Open Beside This Page, Add a Pane on the Right or Left, Open on the Left to Write In and Write here too — plus a reading pane that could only be read and a Side by Side mode that could only hold two. They are one command now, and every pane is the same.

Show another page in a pane

Any pane can show any page, and changing what one shows leaves the others as they are.

  1. Click into the pane. Click its page or its bar. The pane you are in wears a quiet ring and a tinted bar.
  2. Choose the page. Click it in the Pages panel, or press ⌘J (View ▸ Go to Page), type a few letters of its name and press Return, or click a link on the page that pane shows. The page opens in that pane, and only that pane changes. ⌘-click a page in the Pages panel to open it in a new tab of that pane instead.

◀ ▶ in the pane's bar go back and forward through the pages shown in the tab in front.

A link follows your setting. By default, a link opens in the pane you clicked it in — a link to a PDF or another file in a new tab of that pane, so the page you were reading stays. If under Settings ▸ Links & Pages you chose Open links and results in a new tab, it opens in a new tab of that pane; if you chose Open Beside the page you are in, it opens in a new pane to the right instead. The Pages panel and ⌘J always use the pane you are in.

  • A new pane: Open Beside adds one, as described above.
  • A page that is already open in another pane is not opened twice: that pane lights up and the status line says which pane it is. To have it here instead, drag its tab into this pane's bar.
  • Moving a pane: drag its tab to the left or right edge of another pane. A pane with one tab moves there whole; from a pane with several, the tab you drag moves into a new pane there.
  • + makes a new page. The + in a pane's bar makes a new, untitled page in your wiki and opens it in a new tab of that pane.

Every pane is a whole page

  • Type in any of them. Click into a pane and the keyboard is there. Formatting, links, lists, pasting, dictation and Find work in it exactly as in the first, and it saves to its own page. The pane you are in wears a quiet ring and a tinted bar.
  • Each pane has its own tabs and its own ◀ ▶ for Back and Forward. + makes a new, untitled page in a new tab of that pane, ⌘W closes the tab you are in (and the pane, with its last tab), and ⌘1 to ⌘9 pick a tab in the pane you are in. A page that arrives on its own — a web clip, an import — opens in the pane you are in, in a tab with nothing of its own to show if it has one, rather than adding another.
  • One page, one pane. A page is open in one place at a time. Ask for a page that already has a pane and that pane lights up, instead of a second copy appearing. Going Back (or Forward) to a page that is open in another pane shows a card in the pane you are in, saying which pane has it; its tab reads In pane 2: … while the card is there. Go there takes you to that pane, with your caret where you left it. Bring it here saves the page, closes it there and opens it in this pane. The card keeps up with the page: drag its tab or move its pane and the card names the pane it is in now, and both buttons go there; close that pane and the page opens in the card's place. A day in the Journal or a sheet of a Longform document that is open in another pane is shown read-only where it appears a second time, with Go there beside it.
  • Words travel between panes as a copy. Drag or paste text from one pane into another and it arrives cleaned the way any paste is, while the original stays where it was. Outline rows, and blocks moved by their ⠿ handle, move only within their own page: dragged over another pane they stay put, and MojoPad says so.
  • The Outline and Page Styles open at the right-hand side of the window, outside every pane, and act on the page you are in.
  • Boards, maps and the views that fill a pane — the graph, Tasks, the Journal, search results and the rest — open in the pane you are in, as many at once as you have panes. See Views in any pane below.
  • One format bar, over every pane. It formats the page you are in, and it stays exactly where it is as you click from pane to pane: over a paper, a board, a plain-text page or a view, the buttons that cannot act there are hidden where they stand, so nothing below the bar moves under your pointer.

Views in any pane: a board beside your draft, two views at once

Every pane can hold a board, a storyboard, a mind map, the graph, Tasks, the Journal, a folder as one Longform document, the gallery or a database view, or search results — and several panes can hold them at once. Some of the ways that helps:

  • A board beside your draft. The cards of your argument in one pane, the chapter you are writing from them in the next, so you can look across while you write instead of switching back and forth.
  • Two boards, or a board and a mind map. Move ideas from a board of evidence to a board of the argument, or keep the map of a chapter beside the board you are planning it on.
  • Tasks beside the graph. Check off what you planned while the graph shows how the pages it touches connect.
  • The Journal beside the page you are writing. Today's notes in one pane, the draft they feed in the other.
  • Two searches at once. Search for one idea in one pane and another idea in the pane beside it, and read the two lists of results side by side.

How they behave:

  • A view opens in the pane you are in. Click into a pane, then open the graph, Tasks, the Journal, the gallery or a folder as one Longform document, or search from the Search box: it opens there, and the other panes keep what they were showing. A link to a board or a map opens it in the pane you clicked in, like any page, and its tab can be dragged or moved to any pane.
  • Each view answers for its own pane. Each board keeps its own zoom, the cards you picked, the card you are writing in, its own Find and its own Undo, and saves to its own page. Scrolling or zooming over a board beside you moves that board. Esc closes the graph or the search results in the pane you are in, and leaves Find, a search or the graph in another pane as it was. ⌘F in a pane holding the Journal filters that Journal; in the pane beside it, it finds in that page. The arrow keys and a paste in a paper or a page stay there, never reaching a board in another pane.
  • A search in one pane leaves a search in another standing. Each keeps its own results, its own checks by meaning and its own Back: open a result in one pane and Back in that pane returns to its search. Searching again in the other pane, or pressing Esc there, never stops this one.
  • Two Tasks views stay in step. A task checked off in one is checked off in the other.
  • A day of the Journal is written in one place. With the Journal in two panes, or a day open as a page in another pane, the second copy of that day is shown to read, with Go there beside it.
  • Nothing else moves. Opening a view beside the others leaves Find open where it was, leaves the Pages drawer where it was, and the format bar keeps its height, so no pane shifts under your pointer.
  • A board's Undo goes with the board. Work on a board in one pane, open it later in another, and ⌘Z there takes back the last change made to it, wherever that was made. Opened beside your page, a board leaves you where you were and opens the Card panel with it.
  • The Search box says the search of the pane you are in. Go to a pane with results and the box shows what that pane asked, so a word typed there refines that search; in a pane with none, the box is empty.
  • Each storyboard has its own Send. With two storyboards side by side, Send opens its panel on the one you pressed, and Create page makes that one's page. On a board, ▶ walks that board alone.
  • Narrow panes. On a laptop, Tasks beside two other panes shows its tasks and puts the list of views and projects behind the ☰ button in its header: press it to pick Today, Upcoming or a project. The Journal's header goes onto two lines, with the filter on the second.
  • Excerpt Mode and boards. With a board open in any pane, ✂ Excerpt Mode puts what you copy on the board you were in most recently, and Send Block to Canvas puts its card on the board as it stands on screen.
  • They come back. A desk, and the wiki as you left it, put each board and map back in its pane — a map beside its notes in either order.

Arranging them: comparing three papers while you write

Say your draft is on the left and three papers stand beside it: a steroid trial, a splinting study and a surgical cohort. As you write, you want the two you are comparing right now side by side, the third out of the way but one click from coming back, and the page you just looked up kept behind the paper it belongs with. Panes are arranged for that in three ways, and none of them happens unless you do it.

  • Drag a tab. Press on a tab and move it. A line shows where it will land: between two tabs of a pane's bar, to move it into that pane at that place; or down a pane's left or right edge, to open it in a new pane there. Let go over another window or the desktop and it opens in a window of its own. It is always a move: the page leaves the pane it was in, so it is still in one place. The tab you carried is the one in front where it lands, and a pane whose last tab you carry away closes. Drag a pane's only tab to another pane's edge and the whole pane moves there, keeping its color and its width. Press Esc while dragging to put it back where it was.
  • Move to Pane ▸ does the same from a menu. Right-click a link, a tab, or a page in any list — the Pages panel, search results, a database view — choose Move to Pane, and pick a pane by its number and the page it shows, or New Pane on the Right (offered wherever it would move the page). A page open nowhere opens there as a new tab; a page open in another pane moves. Your caret stays in the sentence you were writing, and the pane it went to lights up. Choose the pane you are writing in and the page goes into a tab behind your page, so the sentence you were writing stays in front. From the keyboard, Move to Pane… in the command palette (⇧⌘P) moves the page you are in, chosen with the arrow keys and Return.
  • Fold a pane. ⋯ ▸ Fold Pane turns a pane into a narrow strip at its place in the row, with its number, its color and its page's name down it; the open panes share the room it gave up. The pane keeps its tabs, and a thread from your draft to its paper still arrives, on the strip — running along the edges of any open pane between them, never across that pane's words. Click the strip — or reach it with Tab and press Return or the space bar — and it opens where it stood. Unfold All Panes opens every strip at once. Asking for a page that is in a folded pane (a link, Go there) opens its pane too. The last open pane cannot be folded.

A page behind another in a pane's tabs keeps its own color, shown along the top of its tab, and a thread from a sentence that mentions it ends on that tab. So the splinting study, filed behind the steroid trial, is still tied to the words that cite it; click its tab to bring it forward.

The pane bar

With more than one pane open, each has a bar across its top: ◀ ▶, the pane's thread dot ● (or ✎ on the pane the threads start from), its number, its tabs and +, ⋯ and ✕. While a board is open for excerpts to land on, a pane showing a page or a paper also has ✂ for Excerpt Mode. A pane with one tab gives that tab the whole bar, so its page's name reads in full, and its ✕ is the pane's own. In a pane too narrow for all of it — three panes in a laptop window, say — ◀ ▶ and + move into the ⋯ menu as Back, Forward and New Tab, and the toolbar's own ◀ ▶ still act on the pane you are in. The ⋯ holds:

  • Draw Threads From This Pane — threads start from the page you are writing, and this chooses which pane that is. Clicking into another pane to read or copy does not move them.
  • Swap with Pane on the Left and Swap with Pane on the Right.
  • Move Pane to a New Window — the pane goes to a window of its own with every one of its tabs, in the same order, the same one in front. It closes here only once the new window has them. A pane of more than a hundred tabs stays where it is, and the status line says so: close some of its tabs first.
  • Fold Pane and, while any pane is folded, Unfold All Panes.
  • Close Pane.

From the keyboard

View ▸ Next Pane (⌥⌘O) and View ▸ Previous Pane move the keyboard from pane to pane and put the caret back where you left it in each; with only one pane open, ⌥⌘O asks which page to open beside. ⌥⌘↩ opens the link at your caret beside, or asks which page when the caret is not in one. View ▸ Close Pane closes the pane you are in. The same commands, and the ones on ⋯, are in the command palette (⇧⌘P), with Move to Pane…, Fold Pane and Unfold All Panes — so moving a page to another pane, folding and unfolding need no mouse. Next Pane and Previous Pane step over a folded pane rather than opening it.

Sizing them, and narrow screens

Panes share the width equally — the page you are writing too — so four papers and a draft on a large display, or a draft and two papers on a laptop, each get the same room. Drag the line between two panes to give one more room; a pane you have dragged keeps its width while the others make room around it — folding and unfolding a pane beside it included — and a double-click on the line shares the room equally again.

Panes narrow as you open more. When there is no longer room for all of them, the page you are writing keeps a width prose is comfortable at, the others stop at the narrowest a pane is drawn, and the row scrolls sideways rather than squeezing anything further: scroll it to reach any pane, and every pane's buttons come with it. The first time that happens, the status line suggests folding the panes you are not reading (⋯ ▸ Fold Pane). Nothing folds, moves or resizes by itself. A narrow pane lays a paper or a book out more tightly, so it stays readable there.

They come back

Quit with panes open and they are there the next time you open the wiki, each with its tabs, in its color, at the width you dragged it to, and folded if you folded it. A desk (View ▸ Desks) keeps them too, widths and folds included. A desk saved on a larger display fits a smaller one: the widths you dragged shrink together, keeping their shape, until every pane has room. A desk or a session saved by an earlier version comes back as panes: the reading pane, the columns and both halves of Side by Side each become a pane, in the order they stood, sharing the width equally. No two papers beside the page you are writing wear the same color as long as there are colors left.

If something looks wrong

Help ▸ Save Diagnostic Report… has a line in its Rendering section beginning Panes:. It says how many panes are open and how many tabs each holds, how many are folded, which pane has the keyboard, which the threads start from, which view each pane shows (the graph, Tasks, the Journal and the like), how many page colors are worn, and whether every pane carries the same editing safeguards as the first. It is counts only, never a page's name or a word of it.

A second window on the same wiki

A small window is a card: one page, floating, for glancing at. Sometimes what you want is a second workspace — two real windows on one wiki, so a long document can sit open on one screen while you write against it on another, each with its own tabs.

Window ▶ New Window for This Wiki opens one, and so does Open in a New Window on any page list, which opens the second window straight onto the page you picked. It is in the command palette (⇧⌘P) too, and Settings ▶ Shortcuts will give it a key of your own — it ships without one, because every combination a hand reaches for is already taken. Asking for it from a second window does nothing and says so: a new window comes from the one you opened the wiki in. It is a full window: its own tab bar, its own Pages panel, the toolbar, find, the outline and the format bar. Pages you write in it are saved exactly as they are anywhere else, and both windows stay in step — save in one and the other has it a moment later, with the same warning bar as always if you were both editing the same page. If your cursor is in that page when the other window saves it, the words under your cursor stay put until you leave the page, and then change where they are — in any pane or a day of the Journal as much as on a page of its own. If you were in the other window when it saved, the change is already showing when you come back. Type there first, and the bar asks which to keep — Use theirs or Keep mine — before anything is saved. That goes for a storyboard, a mind map and a canvas too, a thought you are still writing on one included, and the answer always goes to the page the bar names, even if you have clicked into another pane since. While the bar is asking, a rename, a tag, a property or a line an assistant adds goes onto both versions, so whichever you choose keeps it; and closing the window or quitting before you choose asks first. A page locked with a password of its own works the same way in both windows. If it locks again while the bar is asking — after the time set in Settings ▶ Security — your version and theirs are locked away with it, and neither stays on screen; unlock it and the bar is still asking, with both. Keep mine also works while it is locked. Writing in a property that holds prose asks nothing: it is not the page's words, so what you write there and the other window's change are both kept — and so is a thought typed on a mind map in the pane beside your page. A rename from the other window asks nothing either: what you type is saved under the new name, and every pane and stack shows it.

A password put on a page in the other window protects it here too, at once. If the page is open in this window, it locks: its lock screen takes the page's place, wherever the page was showing — any pane or a small window as much as the page on its own. If you were writing in it at that moment, nothing you wrote is lost, and nothing is saved without the password. Your words stay in this window, and a bar says a password was put on the page, with two ways on: Unlock… opens the page with its password and then asks, as above, whether to keep your version or theirs — whichever you keep is saved with that password — and Export my changes… saves your words to a file you choose, outside the wiki, for when you don't know the password. There is no Keep mine on that bar: it would save your words without the password. The same happens when the password is changed in the other window. When it is taken off there while you are writing, the bar offers Use theirs, which shows the page as it now is, with no password, and Export my changes…: your words were written while the page had a password, and they are not saved without one. In case MojoPad closes unexpectedly while your words wait, it keeps a copy of them on this Mac, locked with the page’s password — the one you last unlocked it with — and offers it back the next time it starts (see Two Macs and a password). While either bar is up, closing the window or quitting asks first, and after the time set in Settings ▶ Security the page is covered by a lock screen with the same two ways on — when the password was changed or taken off, Export my changes… there first asks for the password your words were written with. While the bar is up, your words in that window are kept from everything that leaves it, as any page with a password is: a connected assistant, search, exports and a page that shows this one inside itself. A password put on, changed or taken off on another device is handled the same way, and a password taken off there is said when it arrives. And Encrypt Page… on a page that is locked here asks you to unlock it first, rather than offering to take its password off.

What the second window does not do is rearrange the wiki. Folders, pins, properties, kinds, saved views, page styles, desks, the sort order and your flashcard reviews are all kept in the window you opened the wiki in — saving a desk says so before it asks you for a name. Try one of them in the second window and it says so; the rest of the time a quiet Second window chip in the status bar is there to be hovered or clicked for the whole explanation.

There are two kinds of gesture here, and they behave differently. The ones that are only a change to the arrangement — a pin, a folder dragged somewhere, a rename — go through on the screen in front of you and are not kept: reopen the window and the arrangement is as it was. A sentence says so the first time and then not again for half a minute, so a run of them can look entirely successful. Make those in the window you opened the wiki in, where they hold.

The ones that would change your pages as well are declined before they start. Deleting a property, changing a property's type, importing kinds or references, merging another document into this one, making a new page type, and the two commands on a followed folder all say no and do nothing at all. That is the more important half, because those gestures write the wiki and your pages, and a second window is allowed to write pages. Deleting a property here took its answer off every page, which cannot be undone, and left the property itself standing — empty — the next time you opened the wiki. Choosing to stop following a folder sent its pages to Recently Deleted while the folder went on being followed, so every file arrived as a page again on the next open. Each of those commands now refuses at the door, before anything is touched, and names the window to do it in.

Importing files is not on that list, because importing is writing pages and that is what a second window is for. The one part of it that cannot land is a field a file brings that this wiki has no property for yet: those fields are left rather than written somewhere nothing could find them, and the import names them when it finishes. A field the wiki already has a property for is filled as usual, here or anywhere.

Nor is filing them — and the notice says which of the two happened. Drop files on a folder here and the pages arrive, unfiled, and it tells you so rather than naming a folder they are not in. File them yourself in the window you opened the wiki in, whenever you like; the pages are already saved and waiting.

That holds for every way something can land in a folder, not only the obvious one: a folder of notes that arrives arranged in folders of its own, File ▶ Import's part-by-part plan, a paper handed to MojoPad from outside, an emailed page and the files it brought, the export Table of Contents, and the folders MojoPad makes without being asked — for pages born on the task surface, for today's note, for a kind. None of them draws a folder here that the next open will not have. A day in the Journal is the one that still lands: what puts an entry on its date is a mark on the page, which is the page's own, not the wiki's arrangement.

Following a folder is done in the window you opened the wiki in, too: Link a Folder says so here before it asks you for one. A folder you already follow keeps working while the second window is open — the wiki's own window takes in what arrives, and the new pages turn up in both — and if that window closes, the second one takes the following over along with everything else.

Why that limit exists, because it is worth knowing rather than guessing at: a wiki's arrangement is kept as one thing, and each window holds its own copy of it while it is open. If both windows could write it, the one that saved last would quietly replace everything the other had done — a folder you made, a page you pinned — with no sign that anything had gone. Pages are different: each is its own, so two windows can write different pages all day without touching each other's work. Making the arrangement behave like the pages is the next piece of this, and until it is built the second window is honest about what it keeps.

Close the wiki's own window and the second one takes over. It becomes the window that keeps the folders and the rest, its chip goes, and it says so — so you are never left with a window that can only point at one that has closed.

It reads the wiki before it writes it. While both windows were open, the other one was the only one keeping the folders, pins and properties — so the moment it closes, this window catches up with everything that was done there, and only then starts keeping them itself. That order matters: before it, the window took over still holding the wiki as it had been when it opened, and the next pin wrote that back over everything the other window had done in between. The folders you had open here are drawn from the wiki as it now stands, which is the small price of catching up.

If the wiki cannot be read at that moment — it moved, or it is still coming down from a sync — the window stays as it was and says so, rather than taking over with a copy it cannot trust. Reopen the wiki and it takes over cleanly.

A few smaller things follow from the same rule. The second window opens on the page you sent it to rather than restoring your tabs, and it does not remember its own tabs when it closes — your places belong to the wiki's own window. It does not run the wiki's page scripts, which the first window has already run. It does not take clips from the web clipper, because filing one is a change to the arrangement. And Open Recent in it opens that wiki in a window of its own rather than taking this one somewhere else. Close it whenever you like; nothing depends on it.

A page in its own small window

Sometimes the reference you keep glancing at deserves its own little window — checklist, style guide, the page of numbers you're writing against. Right-click any page and choose Open in Small Window: the page opens as a compact card that floats above your other windows, so it stays in view while you write anywhere else — even in another app.

Any page, from any list. Not only the sidebar: search results, the Context, Backlinks, Related and Rediscover panes, the Pages pane, and the list you check sources from all offer the same right-click — Open, Open Beside, Open in Small Window and Open in a New Window. Comparing two results no longer means opening one, going back, and running the search again.

If you would rather it behaved like any other window and went behind whatever you switch to, turn off Keep small windows in front of other windows in Settings ▶ Links & Pages. Cards already open change the moment you do.

The card opens as a live reading view: edit the page in the main window and the card updates the moment it saves. Links inside it work. Close it like any window (⌘W), or click Open in Main Window to continue in the full app — it arrives as a new tab, so the page you were working on is still there when you come back, and the card closes behind you. If that page is already open in a tab, you land on that one rather than getting a second copy of it.

And you can write in it. Click the ✎ pen in the card's header and the page becomes editable right there, with the same formatting controls and the same Find and Replace as the main window — jot the thought, check the box, rewrite the paragraph. The pen becomes 👓 eyeglasses; click again to go back to reading (your edit saves as you go, and the main window mirrors it the moment it lands). If the same page ever has unsaved changes in two windows at once, MojoPad never guesses: a small bar appears — Use theirs / Keep mine — and nothing is overwritten until you choose.

Open as many cards as you like: each is its own window, so you can draft in one, keep a source open in another, and work on a translation in a third, sized and placed however suits you.

📓 Book Notes — the reading room in one click

Every PDF and ePub's toolbar has a 📓 Book Notes button. Click it and MojoPad assembles your reading room: it opens (creating it the first time) a page named <Book> — Notes, opens the book in a pane beside it, and files the pair under Books ▸ that book — each book on its own shelf. Nothing you've already filed is moved. From there the excerpt loop below does the rest: drag a passage across and it arrives quoted, linked back to the exact spot — notes that argue with the book, page by page.

Writing with the keyboard and want to scroll the book without reaching for the mouse? View ▸ Next Pane (⌥⌘O) hops the keyboard between the two. While the book's pane holds the keyboard it wears a quiet ring, and the arrow, space, and page keys scroll the reading — press ⌥⌘O again and you're back in your sentence, where you left the caret.

Your layout comes back. The two panes are remembered for the wiki — reading on one side, notes on the other. Quit MojoPad, reopen the wiki later, and the book is back in its pane beside your notes, so you pick up exactly where you were. Close the pane and it stays closed next time.

And the book remembers your place. A PDF or EPUB you're reading resumes where you left off next time you open it — a PDF at the same page, an EPUB at the same spot in the same chapter (anchored to the chapter, so it holds even if you resize the pane or change the reading font). This works in the first pane too, not just the one beside it. EPUBs are reflowable and have no fixed page numbers, so the place is remembered as a position within the book rather than a page count.

Zoom a PDF with the small − 100% + pill at the reader's lower right — or ⌘+ / ⌘− while your pointer is over the pages, ⌘0 to snap back to fit width, or a trackpad pinch. Pages re-render sharp at any size (never a blurry stretch), your highlights stay exactly on their words, and each document remembers its zoom along with your reading place.

PDFs and books read fully in the pane — real pages, selectable text, and the excerpt loop below. The book's pane is a pane like any other, with its own tabs in the bar across its top, and any page can stand in it: a page link clicked there opens in that pane — or beside it, if that is what you chose under Settings ▸ Links & Pages — and ⌥-click always opens it beside. To put the book on the other side, choose ⋯ ▸ Swap with Pane on the Left in its bar; ✕ in the bar closes it, and dragging the line between the two panes resizes them — the width comes back next time. All of what a pane can do is in Panes: several pages side by side, each with its own tabs, earlier in this chapter.

Excerpt into your notes

Reading a PDF or book in the pane, pull the good bits straight into the page you're writing: drag a selection onto the note (or ⌘C it, then ⌘V on the page) and it lands as a quote — dropped as its own block, never split into the line you were on — with a ↩ backlink to the source and its own highlight left in the document. With ⌘C and ⌘V, paste within half a minute of the copy: after that, or if you copy something else in MojoPad first, you get the words alone, with no quote around them. The quote is made only in the page itself: pasted or dropped into a property, a plain text page or a Markdown page in the raw source view, the words arrive as they are. In the Journal, the quote goes into the day you are writing in: click into another day to quote into it. Click the ↩ and the source opens in a pane beside your page at that exact spot — or, if a pane already shows it, that pane goes to the spot — with a thread drawing from your quote to the highlight. The same gesture works on a rich-text page, a Markdown page, or a canvas card, so an idea always leads back to where you found it.

Drag a selection right away. In a paper kept in your wiki, press anywhere on the words you selected and move: the drag starts at once, with no need to hold the pointer still first, and a slip of the hand as you press doesn't lose your selection. Everything else you do on the selected words works as it always has — a click clears them, a double-click selects a word and a triple-click a line, ⇧-click extends the selection, and right-click opens its menu. To start a new selection that begins inside the selected words, click once to clear them, then drag. Dropped into another app, the passage arrives as the same text it always did. A paper read in place from a folder works as before: hold the pointer still for a moment, then drag.

A passage that runs over a word the paper split at the end of a line — tin- on one line, gling on the next — is quoted and highlighted like any other, and the quote writes the word without a gap.

Each excerpt owns a separate highlight, so quoting the same passage in two places never tangles them. Highlights are permanent marks: right-click one in the reader to remove it, or clear them all at once with the button on the bar above the paper or book that says how many there are — Clear 3 highlights, say — in whichever pane it is open. It asks first.

Your marks are readable by an assistant

What you highlight is the most considered thing on the page. Somebody decided, one passage at a time, that this mattered — and a connected assistant can now read exactly that, rather than being handed the whole document and left to guess. It gets the passages in the order you read them, each with the place it sits in the work (page 7, chapter 3) and the day you made it. A highlight in a paper also comes with the color you chose for it, when you chose one. A highlight in a book carries no color of its own — MojoPad marks a book in one shade, with none to choose — so none comes with it. Each one also comes with a link that opens the paper or the book at that mark, the kind of link your own excerpts carry, so a page an assistant writes from your marks can link each passage, not only the paper it is in.

So you can ask for a timeline built only from what you marked across twenty papers, with every line citable back to the page it came from. There is a ready-made way to ask — from-what-i-marked under AI Agents — and it is told not to fill the gaps from the papers themselves, so where your marks run out it says so instead of writing something that reads the same and is not yours.

What a color means is yours, and nothing guesses at it. If yellow means evidence to you and pink means I do not believe this, that is worth saying out loud when you ask; a paper's colors come back by name and no meaning is assumed.

A page with a password gives no marks at all. What you highlighted is part of what the password covers — a mark holds the passage itself — so it is sealed with everything else, and an assistant is told the password is the reason rather than being handed an empty list.

If you encrypted a page before this, its marks were written beside the ciphertext rather than inside it — a page already on disk is not changed by MojoPad learning better. Nothing in MojoPad will read them, but they are in the file. Help ▸ Diagnostic Report has a line under What you have marked while reading that says how many pages are like that, and on almost every Mac it says none. Unlock such a page once and it is re-sealed with your marks inside.

Link a report to the passages it quotes

A link can carry the words of a passage in one of your PDFs, not just the paper. Click it and MojoPad opens the paper at that page, finds the words, marks them, and draws a line from the link to the mark. Three ways people use it:

  • A report an assistant writes for you. You ask Claude, connected to MojoPad, to read the papers in a folder and write a page on what they say about one question. Every claim in that page ends in a link to the sentence it rests on — and one click shows you the sentence, marked, in the paper beside the report, so you can check the claim against the source instead of trusting it.
  • A script that builds report pages. A program that writes pages into your wiki on disk, with the wiki closed, can write the same links. Nothing is marked until you click one, so the script never touches your marks.
  • Your own notes, pointing at the evidence. A reading note that says the cohort was small (p. 4) can link to those exact words, and keep working in a copy of the wiki, or after the mark was removed.

Your first one, in a minute

  1. Open a page an assistant wrote with links like these — they look like any other link.
  2. Click one. The paper opens beside the page (or moves, if it is already open in a pane) at the page the link names, the quoted words turn yellow, and a line runs from your link to them.
  3. Click the same link again: MojoPad goes to the same mark. It never lays a second one over it.
  4. Right-click the mark. The first line of its menu says Made from a link on “your report”, which opens the report; below it are the colors and Remove highlight, as on any mark.

Every passage at once

On a page full of these links, choose Edit ▸ Links ▸ Mark the Quoted Passages (also in the command palette, and on the right-click of any such link). MojoPad reads each paper out of sight, marks every quoted passage it finds, and ends with one sheet: Marked 12 passages in 4 papers; 2 quotes weren’t found, the quotes it could not find with the page each was looked for on, and any paper it left alone and why. Remove the marks this made on that sheet takes back exactly those marks and nothing you marked since. A passage that is already marked is not marked again, and neither is one you mark, or reach by clicking its link, while MojoPad is still working. If a paper is locked, or the wiki locks, before MojoPad finishes, the sheet lists each paper it didn’t finish and how many quotes are left in it. A paper whose password was changed on another device while MojoPad was marking it is listed too: answer the bar at the top about it first, then mark its passages again.

How the words are found

The link names a page, and MojoPad looks there first, then on the page after, the page before, and two pages either way — never further. A link names the page by the PDF’s own count, starting at one, and the numbers printed on a paper’s pages are often different: a page or two later when the PDF adds a cover sheet, and a journal’s own numbers, which run through the whole volume, can be in the hundreds or thousands. A quote at the foot of a page is often counted as the next. Past two pages, the same words are more likely a different passage than a miscount, so MojoPad stops rather than mark the wrong one. A link that names no page, or a page past the paper’s last one, is looked for through the whole paper.

A quote that runs from the foot of one page onto the top of the next is found too, past the page number and the heading printed between the two halves. A mark is on one page, so MojoPad marks the part on the page that holds more of it.

Only letters and digits are compared, in any language. Spaces, line breaks, punctuation, curly or straight quotation marks, the different dashes, a word broken across a line with a hyphen, the invisible hyphens some papers carry, and letters a font joins together (the fi in finding) are all taken as the page has them. Capitals are compared as written first, and only if that finds nothing are they ignored. A quote of fewer than eight letters is not looked for at all, because it would match on every page.

A manuscript with numbered lines. A paper under review prints a number beside each line, and in the paper’s text that number stands between the last word of one line and the first word of the next. MojoPad recognizes a column of line numbers in the left or right margin and reads the lines without them, so a quote that runs from one line onto the next is found whether or not it repeats the number, and a word broken at the end of a line — inter- on one line, vention on the next — is found written as intervention, inter-vention or inter- vention. The mark covers the quoted words only, not the number beside them. Numbers that are part of the text — a count, a figure’s number, a footnote — are read as the words they are. A table whose rows are numbered 1, 2, 3 down the very edge of its page, with nothing further out, can look like a numbered margin: a quote of one of its rows is still found, though its mark may leave out the row’s number.

When MojoPad doesn’t mark

  • The words are not there. The paper opens at the page the link named — or at its first page, when the link names a page the paper doesn’t have. A link that names no page leaves you where you were reading. A notice at the bottom of the window says MojoPad couldn’t find the quoted words on page 4 of “Smith 2020”. It stays until you press OK. The usual reason is a quote written from a different version of the paper — a web page, a preprint — than the PDF you have.
  • The paper has its own password and is locked. It opens on its lock screen and nothing is marked: its marks are sealed with it. Unlock it and click the link again. A mark made on such a page is sealed under its password, like every mark. If the bar at the top says the paper’s password was changed elsewhere, answer the bar first, then click the link again.
  • The paper is one MojoPad reads from a folder on your Mac rather than holding a copy of. MojoPad never keeps marks in those, because the file can change under them. The paper opens at the words and the status line says why there is no mark.
  • The link came from another app — a Word file you exported, a mail message. Any program on your Mac can send MojoPad a link, so a link from outside never makes a mark by itself: MojoPad opens the paper at the words and offers Mark them, and the mark is made only when you press it.
  • The quote is too long or too short to look for, or the link points at a page that is not a PDF. MojoPad opens the page and says so.

And a link to a mark that has since been removed — a citation from an excerpt, or a link you made with Copy Link to Selected Words — no longer opens the paper in silence: it says MojoPad couldn’t find the marked passage this link points to, and, for a citation that names a page, which page it opened instead.

What an assistant sees

No assistant can mark your papers: there is no tool for it. An assistant writes the link, and your click makes the mark. When an assistant later reads what you marked, a mark made from a link comes back labeled as one, so it is not reported as a passage you chose. The words a link quotes are never written to MojoPad’s log, and the diagnostic report counts these marks — reading highlights: 40 (12 made from a link) — without saying what they say.

Writing one by hand

The link is written mojoref:, the paper’s page id, then the parts it needs, each after a semicolon:

mojoref:<page id>;pdf=4;q=the%20cohort%20was%20small

pdf= is the page, counted the way the PDF counts. q= is the words, written the way a web address writes them — a space as %20, and most punctuation the same way — at most 500 characters. Add c=green (or amber, pink or blue) for a color other than yellow. A link that also names a mark, with hl=, goes to that mark while it is there and uses the words when it is not. The words survive a Markdown page, a Markdown export and a Word file; in Word the link still opens MojoPad at the passage. A part MojoPad doesn’t recognize is skipped and the rest of the link still works, and a color it doesn’t have is yellow — though a Word export leaves a link like that out and lists it with the links it couldn’t keep. An assistant connected to MojoPad is told all of this; you only need it to write one yourself.