Graph view

Open
  • Is something wrong?
#183 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
22/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
d3, typescript
Domain
backend, data-visualization, frontend

Research direction

Start with read(text).links in packages/pages/src/reading/reading.ts and getReferences / linking in packages/pages/src/blocks/queries.ts to see how wikilinks are parsed and how backlinks are found today. The first decision is whole versus local graph, and the open questions on journal pages, empty pages, and block refs need a maintainer answer before coding. Done means a single query returning all pages and { from, to } edges, exposed to the renderer, plus a navigable graph view.

Written by the indexing model from the issue text.

Description

enhancement

A view that draws the ledger's pages as a graph: one node per page, one edge per [[link]] between them. Click a node to go to that page.

Why

Links are already the main way pages relate, but you only see them one page at a time, as references at the bottom. A graph shows the whole shape at once: which pages are hubs, which are islands, and how knowledge written by different people connects. That fits the knowledge-sharing side of pbnotes.

What is already there

  • read(text).links in packages/pages/src/reading/reading.ts gives the wikilinks in a block.
  • getReferences / linking in packages/pages/src/blocks/queries.ts answer "what links to this page", one page per call. The graph needs every edge at once, so it wants a single pass over all blocks that returns { from, to } pairs (canonicalized titles, no self-links). The ponytail note on getReferences already points at a reverse index; this pass could be that.

What to do

  • A query in packages/pages that returns all pages and all page-to-page links in one pass.
  • Expose it to the renderer the same way the other page queries are.
  • A graph view in the renderer: force-directed layout, pan and zoom, node size by link count, click to navigate (through the renderer's navigation, #167).
  • A way to open it (shortcut and/or a place in the trail).

Open questions

  • Whole graph or local graph first? A local graph (this page and its neighbours, N hops out) is smaller, more useful day to day, and sidesteps performance. The whole graph is the showpiece.
  • Journal days. Daily pages link to everything and can swamp the picture. Hide them by default, or offer a toggle?
  • Pages that are linked but have no content. Show them as nodes (dimmed) or leave them out?
  • Block refs. read(text).refs exists too. Count block refs as edges to the block's page, or links only?
  • Library. d3-force on canvas, or something heavier like a WebGL renderer, depending on how big ledgers get.
  • Properties (#174). Property keys are pages, so property edges could show too. Probably later.

Check before closing

  • Edits from other writers show up in the graph without a reload, like the rest of the app.
  • A ledger with a few thousand pages stays usable.
Dominant language
TypeScript
Stars
0
Forks
1
Avg merge
16m
Merged PRs (30d)
107

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from shovon/pbnotes

All issues in shovon/pbnotes

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.