The topic map

The map draws a collection as a field of dots. Each dot is a card, or several cards that say the same thing (a group). Dots that mean alike sit near each other. Select one to see what it links to, read the passage behind it, or open the book.

The map uses the topics and groups you already have. It never finds topics on its own, and it makes no model call and no network call to open or lay out.

Open it#

• In the panel, on the Topics tab, select Open map. On a topic, Open map opens the map with that topic selected.
• Topic Map: Use: Open topic map in the palette. It opens the map of the collection note you have open, else the collection in the panel, else the library map.
• From a link, such as obsidian://topic-map-map?collection=Garden%20notes&view=network. A link can carry level (library or collection), collection, focus (a card), view (themes, network or words) and shelf. The map's own state is a link, so a map saved with your workspace reopens in the same place.
• From another plugin, or from Claude through topic-map.open_map. See Your collections in Claude.

The first time a map opens it shows its progress ("Finding each card’s neighbors", "Packing families and topics", "Settling the network") with Cancel. After that it opens at once from what it saved. Opening the same map again while it is still being laid out (Open map twice, or a link) joins the layout under way rather than starting it over.

The three modes#

The switch at the top reads Themes, Network and Words.

• Themes packs the dots into their topics, and the topics into their families. Use it to see how the collection divides and which topics sit side by side.
• Network shows one dot per topic, sized by its cards and colored by its family, linked to the topics its cards are most like. The stronger the link, the thicker and brighter the line: a link inside a family takes the family's color, a link between families is gray. Each topic keeps its strongest few links, measured against the topics' sizes so a big topic doesn't link to everything. Use it to see which topics bridge, and which families sit side by side.

Network's dots start where their topics sit in Themes, held near there and drawn to their family, so the two modes look alike and a family reads as a region. When you switch, the cards ease into their topic's dot and fade as the dots come up, and back again. Zoomed out, the families are named; zoom in for every topic's name. Zooming and panning never move a dot.

A collection without topics yet, and the library map, have no topics to show: there Network places every card by how alike its neighbors are, starting from where it was the last time the map was laid out.

Switching is exact: switch back and every dot is where it was. The map remembers the mode per collection. Themes is grayed out, with the reason on hover, when the collection has no topics yet ("No topics yet: run Find topics to see families and topics"). Words shows topics too, so it is grayed out the same way, or until the map has been laid out with its topic network ("Words needs the topic network: select Re-lay out under Layout").

Words#

Words shows the same topics as Network, as words instead of dots. Each family's name sits big at the middle of its topics, and every topic's name sits where its dot would be, sized in a few steps by how many cards it holds and colored by its family. It opens with the field filling the pane, the family names large enough to read; in a pane too small to show the whole field that way, it opens on the field's middle with the names readable and the biggest topics up, and zooming out shows the rest. Family names never overlap each other, and topic names never overlap each other; each word is tilted a little, the same way every time (a long name less). Zoomed out, the family names lead and the topic names are faint; zoom in and the topics come up as the family names step back. Zooming and panning never move a word. Words draws with the page itself, not WebGL, so it works where the canvas can't.

• Move around by dragging, the mouse wheel or a pinch. With the field focused, Shift and the arrow keys pan, + and - zoom, and 0 fits the whole field.
• Select a topic. Its linked topics travel in to a ring around it, the strongest closest and boldest; one in another family keeps its color and carries ↗. The rest of the field dims. Its strongest cards sit under it as smaller words. Select a linked topic to walk to it: it takes the middle, and the trail above the field lists where you've been. Select a name in the trail to go back to it.
• Select a card under a topic to see it in a box: its name, its book, its versions, its linked cards, Read passage, and Open in book in a book collection.
• Select a family's name to fly in to that family.
• Esc or Back steps out: from a card to its topic, then from the topic to the field. Selecting an empty part of the field clears the selection.

With the field focused, the arrow keys move to the nearest word in that direction, and Enter selects it. While a topic is selected, Tab walks its gathered words, strongest first, then its cards. / goes to Find. With reduced motion turned on in your system, the words jump instead of traveling.

List, beside Field at the top of Words, shows the same thing as an outline: families, their topics, and a topic's cards. Each row has up to three colored chips for what it links to most; select a chip to jump to its row. The arrow keys move between rows, Right opens one and Left closes it or goes to its parent. What you select in List is selected in the field, and the other way round. While the map is open, Words stays in whichever of the two you were last in.

Select a card#

Select a dot. The side panel shows its topic, how many books it comes from (or, for a group, its versions, each named by its book and place, with Read passage), and its linked cards with their similarity. A card in another topic is marked with an arrow (↗). + weaker adds the next eight, under Weaker neighbors.

In Network on a map without topics, the linked cards also swing into a ring around the dot, the weaker ones on an outer ring. Select another card in the list to walk along the links. Esc clears the selection, then steps back out of a topic or family. Back does the same.

Select a topic in Network#

Select a topic's dot. It and the topics it links to stay lit, and the rest dim. The side panel shows the topic's name, its family and how many cards it has, then its linked topics, strongest first, each with the link's strength (hover over it for how many cards bridge the two). A topic in another family is marked with an arrow (↗). Select one to walk to it. Under them are the topic's Strongest cards, the ones most like the rest of the topic, each with Read passage; select one to see it in Themes.

Show its cards goes to Themes, flown in to the topic, with its strongest pairs into other topics listed (as Filter to this topic does). Esc or Back clears the selection, then steps back out.

Filter to a topic#

Select a topic name (in the card box, in Find, or in the breadcrumb), then Filter to this topic. The map lights that topic’s dots and lists its Strongest pairs into other topics: pairs of cards, one inside the topic and one outside, that are close in meaning. Hover over a pair to light both dots; select it to go there.

Three controls shape the list: Min similarity, Max pairs, and Other families only. A focused topic or family also lists its links to the others; select one to travel there.

Find#

The box at the top finds cards and topics by name (Find a card or topic; Find a book in the library map). Pick a suggestion to fit the view to it and select it. In Network, a card picked selects its topic, with the card first among its strongest cards; a card in no topic has no dot there, so the map switches to Themes to show it.

Read a passage and open the book#

On a card in a collection map, Read passage opens the passage with the quote highlighted, the same dialog Search uses. In a book collection, Open in book there opens the book in Library Hub’s reader at that place. The map loads the collection’s passages only for Read passage, and lets them go again when nothing else needs them, as Search does.

The library map#

Open it with Topic Map: Use: Open topic map when no collection note is open, or from a link with level=library. It needs the library collection (made from the panel) and Library Hub, which lists your Calibre books. A library map restored before Library Hub has loaded opens once it has. Each dot is one book. It shows books only: no cards, and no Read passage.

• Shelves. Library Hub’s shelves color the books. A book takes the color of the smallest shelf it is on, with a thin ring for up to two others and "+n" for more. Select a book to see its shelves, Open note, Open in reader, and its Similar books. Select one of its shelves to light that shelf: its books keep their color and the rest go gray, and the map’s link carries shelf=. Every book then lists the lit shelf; select it again to show every shelf. A link with shelf= lights a shelf the same way. The map re-reads the shelves when it opens and when you come back to its tab.
• A new book is placed, nothing else moves. The library map saves its layout. A book you add is placed near its neighbors the next time the map opens; the books already there keep their positions. A book removed from Calibre leaves the map.
• Books with no vector are left off, and a line says how many ("index the library to place them").
• Re-lay out under Layout settles every book again, starting from where they were so the map keeps its rough shape, and saves the result.
• Words. In Words, each book is its title, colored by its smallest shelf, sized by how many other books list it among their nearest. Zoomed out on a large library, the shelves' names stand in for the books, which come up as you zoom in. Select a book to gather its similar books around it. A lit shelf grays the other books here too.
• A book that belongs to an indexed collection has an Open its topic map button. Back to the library returns.

The library map only reads. It never changes Library Hub, your shelves or your books.

The Layout fold#

Under Layout in the side panel (closed at first):

• Link Δ: how much weaker than a card’s best match a link may be and still show.
• Max links: the most links one card shows (at least one is always kept).
• Topic pull: how strongly topics gather their dots in Network, on a map that shows every card there (no topics yet, or the library map). It runs only while you move the slider. Where Network shows topics it has nothing to pull, and is hidden.
• Re-lay out: settle the map again and save it.

When the map is out of date#

A saved map goes with the topics, the groups and the vectors it was made from. If you run Find topics, group the cards again, or index, the map says "This map is out of date." with Lay out again, which makes it afresh. Until then it keeps showing the old layout. If you cancel Lay out again, or it fails, the old map stays up, still marked out of date, and the status line says why it stopped. A topic found after the map was made isn’t on it until you lay it out again.

If the groups are out of date, the map uses them and says so. With no groups, each card is its own dot, and the map says why.

What it needs#

• WebGL for Themes and Network. The dots are drawn with WebGL; Words isn't. Where the window can’t get it, the map area says "The map can’t draw here: WebGL isn’t available", with the cause. The side panel, Find and the lists still work. If the window loses its WebGL context while the map is open (the graphics card resets, or too many maps and graph views are open), the map area says so and offers Reload map.
• Library Hub for the library map, and Library Hub 0.7 or later for shelves. An older one says so.
• Model Hub only for a collection whose lens is kept in your vault. A built-in lens needs nothing.
• An indexed collection. Index it first; a map has no cards to draw otherwise.

What it writes#

Opening a map writes map/map.json, map/neighbors.bin, map/layout.bin and map/card-neighbors.bin in the collection’s index folder, and the library map’s under corpora/library/map/library/. They are cached, rewritten when the topics, groups or vectors change, and removed with the index. Each card’s 30 most alike cards (card-neighbors.bin) are the slow part, measured on whole vectors: they are found again only when the vectors, the cards or the topics change, so a new layout or regrouped cards don’t pay for them twice.

Motion#

If your system is set to reduce motion, the map cuts instead of easing between modes and rings.