The problem this solves. You have a few thousand papers, and they already live somewhere — in a reference manager, in a folder you have curated for years, on a drive. Bringing them in the ordinary way would copy every one of them into your wiki: a second copy of everything, and from that moment two versions that drift apart.
File ▸ Read a Library… does the other thing. Point MojoPad at the folder and it makes a page for each paper that says where the paper is — never a copy. It reads the words out of each one, so a paper turns up in search, among related pages, and in answers, exactly like a page you wrote. The papers never move, never change, and the program that manages them never notices.
Sub-folders come too, and the pages are filed under a folder named for the library.
What you are agreeing to. You grant a folder, not a list of files: everything inside it, however deep. That permission stays on this Mac and never travels inside the document — send the wiki to somebody else and they get pages that know a paper's name and nothing they can read, until they point MojoPad at their own copy. Each time a paper is opened, MojoPad checks again that it is really still inside the folder you shared; a shortcut pointing somewhere else is refused, however it got there.
A document with a password can't read a library. The papers would sit unprotected on disk while the pages looked locked, which would be a hole in the protection that you could not see. So it is refused outright rather than half-done.
Highlights are the one thing missing. A highlight remembers a place on a page, and a paper you do not own can be re-downloaded, re-scanned or replaced at any moment — a highlight that quietly slid onto the wrong paragraph is worse than none. So papers read in place can be read, searched, found and quoted, but not yet marked up. Papers brought in the ordinary way still highlight as before.
Stop Reading a Library… withdraws the permission. The pages stay and say they can no longer be read; nothing of yours is deleted, and pointing MojoPad at the folder again brings them straight back. Help ▸ Diagnostics lists which folders are shared and whether every paper is still where its page says.
Plenty of people arrive at MojoPad already living in something else — a document manager holding years of PDFs, a folder of markdown, a reference library. You don't have to move any of it. The most comfortable arrangement is usually a division of labour: the other app holds the documents; MojoPad holds the thinking and the links between them.
Most Mac apps can hand you a permanent link to one of their items — DEVONthink calls it an item
link, and other apps offer something similar. Copy that link, then in MojoPad select the words you
want to link and choose Make Custom URL Link… (⌥⌘U). Now the sentence in your notes
points straight at the source document, and one click reopens it in the app that owns it — at the
right item, every time.
The first time you click a link like that, MojoPad asks before handing it to another app, and offers to always allow that kind of link. Nothing leaves your Mac; the question is just so a link in a document you imported can't quietly launch something.
If a PDF or book is worth keeping in MojoPad, import it and read it here: highlight passages, and drag a selection onto the page you're writing to land it as a quote with a ↩ backlink to the exact spot. See Importing for the whole reading and excerpting flow.
If it belongs in the other app, keep it there and link to it. Many people annotate PDFs in their document manager and keep MojoPad for what the annotations mean — the argument, the connections, the writing that comes out of them.
Nothing here is a one-way door. A MojoPad document is a folder: right-click it in the Finder and choose Show Package Contents and you'll find one plain file per page, plus your attachments as ordinary files. On top of that, File ▸ Export Document writes the whole wiki out as a folder of Markdown, plain text or Word files, as a website, or as a PDF or ePub — and any single page exports on its own from Export Page As.
Sometimes a note shouldn't move in at all. Three cases where that's true:
For those, choose File ▸ New Page from a File… and pick the file. You get a normal MojoPad page — it links, it's found by search, it shows up in the graph, it takes backlinks — except its words live in that file. Type here and the file changes. Change the file in any other app and the page catches up, usually before you've looked back at it. Nothing is copied and nothing is converted.
The page carries a small ⇄ filename mark under its title, so you always know which pages reach outside the document. Click it to show the file in the Finder.
One file at a time is right for a handful of notes. When the thing you want to work with is a folder — an indexed folder, a vault, a repo's notes directory — choose File ▸ Link a Folder… instead. Every text file in it becomes a page, the folders inside it become folders in your sidebar, and files added to it later turn up as pages on their own, whether they were added while you were working or while MojoPad was closed.
That last part is what makes it feel like one library rather than two: clip something into the folder from another app, and a minute later it's a page here, searchable and ready to link.
Files MojoPad can't treat as notes — images, PDFs, anything that isn't text — are left alone rather than turned into pages, and hidden folders are skipped.
A folder is followed all the way down. Sub-folders, and sub-folders inside those, become folders in your sidebar in the same shape they have on disk — so a notes directory of a few thousand files across dozens of folders comes in whole, not just the files sitting at the top level. There is a ceiling, in the thousands, and if your folder is past it MojoPad tells you the real number it found, follows as many as it can, and leaves the rest alone. Two things to know if you meet it:
To see exactly where you stand, Help ▸ Save Diagnostic Report counts each followed folder the same way MojoPad itself does: how many files in it can be followed, and how many of them have pages. When those two numbers match, you have all of it.
File ▸ Stop Following a Folder… ends the arrangement — as does Stop Following in the right-click menu of the folder itself, which is the same thing from wherever you happen to be looking. Files you add to that folder stop turning up here, and MojoPad asks what should happen to the pages that came from it:
Follow the folder again later and the pages you removed come back — the same pages, with their links and their place in the tree — rather than arriving a second time alongside their own ghosts. And if the folder has simply gone missing from your sidebar, choosing Link a Folder… and picking it again puts it back where it was, with everything that came from it inside.
Say you keep your reading notes in ~/Notes, and another app already watches that
folder.
~/Notes.That round trip is the whole feature. Everything else is what happens when it gets complicated.
This is the arrangement most people are after: the document manager holds the documents, MojoPad holds the thinking, and one folder is common ground. Two things are worth knowing.
MojoPad writes into the file, it doesn't replace it. That matters more than it sounds. Apps that save by writing a new file and swapping it out break any link pointing at the old one — so if you keep item links to that document (DEVONthink's Make Custom URL Link, and the equivalent elsewhere), they'd stop working every time you edited. MojoPad edits the file in place, so the item stays the same item and your links keep resolving.
A file created after the folder was indexed needs one nudge. A document manager notices changes to files it already knows about within seconds — that's the direction that matters, and it just works. But a brand-new file appearing in the folder may not show up until it rescans. In DEVONthink: select the indexed group and choose File ▸ Update Indexed Items. This is the other app's behaviour, not MojoPad's, and it catches everyone once — including us, while building this.
The smooth path, then: make new pages from files the other app already knows about, and when you do add a file from outside, run its update once.
One file when a particular note needs to live somewhere specific — a README beside its code, a document someone else edits, a file you also open on a phone. A folder when you want two apps to share a working library, and you want new files to keep arriving without asking.
You can do both in one wiki, and a folder you follow can sit alongside hundreds of ordinary pages. Linked pages are ordinary pages in every other respect: they link, they take backlinks, they're found by search, they show up in the graph, and they can be tagged and given properties like anything else. Those extras live in the document, not in the file — so tagging a linked page doesn't scribble on someone else's file.
The other direction. A page that has been in your wiki for years can be given a home on disk: open it and choose File ▸ Move This Page to a File…, then say where it should live. Its words go into that file, and from then on the page and the file are the same thing — edit either.
What moves is the writing. Its name, tags, properties, aliases and backlinks stay here, in the wiki, exactly as they were; the file gets the words alone. A rich-text page becomes Markdown on the way out, so anything Markdown can't express is simplified — MojoPad says so before it does anything, and you can stop there.
Some pages can't go: a storyboard would lose its shape as a flat file (use Send Storyboard To instead), an imported file or a canvas isn't writing, and a protected page won't be written out in the clear.
If you edit the page while another app edits the file, MojoPad stops rather than guess: a bar appears offering Use the file's or Keep mine. Neither version is thrown away before you choose — pick Keep mine and your text goes out to the file, pick Use the file's and the page takes what's on disk.
.md, .markdown), plain text (.txt), Org-mode
(.org), reStructuredText (.rst), AsciiDoc (.adoc), LaTeX
(.tex), TaskPaper and log files. A markdown file becomes a Markdown page; every other
kind becomes a plain text page, and that is the point — what MojoPad writes back is exactly
the characters that were there, so an Org file stays an Org file rather than being quietly
rewritten as something else.