Portals allow you to display the same notes in multiple places. Inserting a portal is like cutting a window in a sheet of paper bearing your notes, with the main location of the portaled notes stacked behind it: any changes made in either the main location or any portal to it will be reflected everywhere, but you don’t have to show all the content in every portal (you can change the size and shape of the window to show only certain bullets).
Content within a portal is shown with a thick blue line to its left. When your cursor is within the portal, a blue box surrounds the entire portal.
Why use portals?
Consider that it's usually most convenient to take notes in a structure corresponding to the place where you learned something. For instance, you might create a new document for a lecture you’re attending, a video you're watching, or a book you're reading, and write what you learn in there. But it’s usually most convenient to look for, edit, and get creative inspiration from notes in a structure corresponding to how the ideas actually relate to each other. If you read ten books about the same topic, it would be frustrating to have to look in ten different documents every time you wanted to look up something about that topic, much less come up with original insights based on that information!
Portals allow you to have it both ways. You can start defining concepts and writing flashcards in a specific document associated with a single source. If you later find that a concept comes up in other sources or contexts, you can move the notes out of that document and into a central location, while displaying the relevant parts of that centralized information in a portal in the source’s document so that you don’t lose any information if you want to see your notes on that particular source.
References, Tags, and Portals have somewhat similar uses. For ideas on which you should choose, check out What’s the difference between References, Tags, and Portals?
Creating a portal
There are several common ways to create a portal.
By searching for a bullet: If you want to include a portal to a concept that you know exists somewhere in your knowledge base, type
((, search for the bullet, and press Enter to add it in a portal. All of its children will start collapsed, but you can expand them in all the usual ways (for instance, by pressing Ctrl+Down Arrow or clicking the small triangle to the left of the bullet point).
By pasting a bullet: If you can see the bullet you want to add a portal to, copy it by pressing Ctrl+C (Cmd+C on a Mac) with the cursor over it but no text selected, then paste it where you’d like the portal to appear and press
pto convert it to a portal.
From scratch: If the bullet you want to add in a portal doesn’t yet exist but you want to create it in a different location than the current document, press Ctrl+Shift+Enter (Cmd+Shift+Return on a Mac), or use the /portal command and select Add New Portal. An empty portal will appear; anything you type here will get created as a top-level bullet (with no parent document); if you want it to go in a document, you can then press Ctrl+Alt+M (Cmd+Opt+M on a Mac) to move it to that document.
Portals and hidden bullets
Sometimes you’ll want to show some of the children of a bullet in a particular document, but not all of them. In this case, you can press Ctrl+Alt+H (Cmd+Opt+H on a Mac) on the bullets you don’t want to see. These bullets will remain visible in other portals and the original location. See Hiding Bullets for details on this feature.
If, after creating some portals, you add a new child bullet within one of the portals or the original location, it will always start shown in the original location, but start hidden within other portals. This prevents information that might be irrelevant from suddenly appearing in other documents. Of course, you can later choose to show such a bullet in the other documents if it's relevant there by clicking the Hidden bullet indicator and selecting it.
In the example below, we add a new line, "Chloroplasts," in a portal in the "June 25th" document that is also opened as a portal in the "Cell Biology" document. By default, the new line isn't visible in the "Cell Biology" document. If you want it to become visible within that document, you'd need to click the "1 hidden" button in the upper right of the portal and make it visible.
How portals impact a bullet's hierarchy
If you create a bullet directly into a document without using a portal, the bullet becomes a child of that document; the document's name will appear as part of the bullet's full name (for instance, in the document breadcrumb in the upper-left). However, if you place a bullet into a portal, then the bullet's full name is unaffected; only the original location of the content affects its full name.
Editing a portal vs. editing its contents
An important distinction when working with portals is whether you're editing the portal itself or the bullet inside the portal. For instance, if you want to delete something, you can delete the portal (which just removes it from the current document and leaves all of the bullets within it in their original location), or delete the contents of the portal (which removes them throughout your knowledge base).
The essential difference is that:
if you select something inside the portal or use the handle, you're editing the contents of the portal. Text will be changed in the original location.
If you click on the border of the portal (which will cause it to change color) or use the handle attached to the breadcrumb in the upper-right corner of the portal, then you're editing the portal itself.
Search Portals
With a Pro plan, you can create search portals. Rather than having fixed contents like standard portals do, the contents of search portals are defined by a search query and update on the fly as you change things in your knowledge base. See Search Portals for more information.