Backlinks

[JosefJezek]

What version of starlight are you using?

0.15.2

What is your idea?

Could you add support for backlinks?

Automatically list links to pages that reference the current page you are on.

Why is this feature necessary?

Backlinks help readers in exploring a knowledge graph.

Do you have examples of this feature in other projects?

• https://quartz.jzhao.xyz/features/backlinks
• https://help.obsidian.md/Plugins/Backlinks
• https://github.com/binyamin/eleventy-garden
• https://vlad.roam.garden
• https://github.com/MaggieAppleton/digital-gardeners
• https://www.mentalnodes.com/a-gardening-guide-for-your-mind
• https://integralguide.com/Guidebook/%F0%9F%92%A1+Glossary/Psyche/%F0%9F%92%A1+Sleep+Apnea
• https://blog.logseq.com/how-to-get-started-with-networked-thinking-and-logseq/#:~:text=of%20the%20block.-,Backlinks,-Not%20just%20pages

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Interesting idea. I think it might even be possible with a user plugin or component. This is a potentially performance intensive task — you have to extract all links for every page and query those — but if structured in a way that ensures it only runs once, it could be ok.

For large sites, it would still be a bit of a dev server hit: every time you edit a page, you'd have to recalculate for the full site graph again. That makes me a bit hesitant to think of this as a core built-in feature, but I'd be happy to help anyone looking to publish this as a third-party add-on.

Quick sketch of how it might work:

// link-map.ts
import { getCollection } from 'astro:content';

// Calculate the map of site links at the top-level so it doesn't run more than needed
export const linkMap = await generateLinkMap()

async function generateLinkMap() {
  const map = new Map<Link, Set<Page>>();
  const pages = await getCollection('docs');
  for (const page of pages) {
    // Extract each link in this page with your preferred strategy
    const links = extractLinks(page);
    for (const link of links) {
      const pagesWithThisLink = map.get(link) || new Set<Page>();
      pagesWithThisLink.add(page);
      map.set(link, pagesWithThisLink);
    }
  }
  return map;
}

Component that can use this. Could be added with an override to Starlight's footer, or used inline in MDX content:

---
import { linkMap } from './link-map';

const { currentPage } = Astro.props;

const backlinks = linkMap.get(currentPage);
---

<h2>Backlinks</h2>
{backlinks.size ? (
  backlinks.map(link => <SomeMarkup />)
) : (
  <p>No backlinks found</p>
)}

A few parts of the code still need fleshing out here obviously, most importantly how would extractLinks() work? Each collection entry contains a body property (page.body in the code above) that gives access to the raw Markdown content, which could be used to extract links in the cheapest way you can come up with: parse with remark and extract from the AST (accurate but relatively expensive), try to write a cheaper link-focused parser (less accurate but maybe faster), etc. This won’t capture everything unfortunately, notably a MDX component that rendered an internal link would not be picked up, but even as a built-in Starlight feature, we’d face that same problem, just like we do with headings in the table of contents.

[JosefJezek]

maybe regex is solution for extractLinks(), see https://github.com/binyamin/eleventy-garden/blob/77be371da872f14adb827e707b49101920aafaec/notes/notes.11tydata.js#L15

Astro has Incremental Content Caching now... How to use the cache?
https://astro.build/blog/astro-4/#incremental-content-caching-experimental

[delucis]

Astro has Incremental Content Caching now... How to use the cache?

You don’t really use it directly, it just happens during builds — when enabled, after an initial build, content is cached and reused for subsequent builds (until it changes). Not sure it helps with the dev performance concerns I mentioned though.

[stereobooster]

I have experimental project which may help with the task. Basic idea: file watcher + markdown parser + db = "markdown-graph-content-layer-database". Usage looks something like this:

const bdb = new BrainDB({
  root: path.resolve(process.cwd(), "src/content/docs"),
  url: (filePath, _frontmatter) => `${generateSlug(filePath)}/`,
});
bdb.start();

---
import { bdb } from "../lib/braindb";
const { entry } = Astro.props;
const doc = await bdb.findDocument(`/${entry.id}`);
---
<div>
  <b>Backlinks:</b>
  {
    doc &&
      doc.documentsFrom().map((x) => (
        <li>
          <a href={x.url()}>{x.title()}</a>
        </li>
      ))
  }
</div>

Full example is here: https://astro-digital-garden.stereobooster.com/recipes/backlinks/