🔌 Plugin: Notion

[tomharrisonjr]

Summary

Notion is wiki/blog software we use as a home for technical documentation. It can be organized using their concept of a "database", mainly a container for documents. Backstage should have links to Notion databases, either ad-hoc, or database having same key fields as Backstage catalog YAML

Project website (if applicable)

https://developers.notion.com/

Context

We organize by micro-service; teams own microservices. Backstage holds the promise of centralizing and organizing all information related to a given service, but the current integration with Notion, where our rich doc lives, is just a link. It should be able to at least render Notion databases (and maybe pages as well), link to databases by team, service, tag, discover and index new content for Backstage search.

[freben]

Interesting. Is this something you'd like to work on? Sounds like there might be some architecture discussion to be had if that whole idea should come to fruition. I wonder what support Notion has for integrations and embedded rendering and whatnot, for example.

[rvanlaak]

Can you share some insights in why you want to let Backstage take over the rendering of a Notion section? Isn't that where Notion on itself is best at, rendering Notion pages? Maybe an iframe could be enough already?

[Rugvip]

@rvanlaak I think that's the discussion freben said that we need to have, without implying any particular solution

[andrewthauer]

I'm also not convinced rendering notion pages in Backstage would make sense given it might technically be quite difficult to do in a way that provides a nice enough experience vs just using Notion directly. However, just thinking out loud here, I do see some other possible useful integration features between Backstage & Notion such as:

• Using a Notion database as data for certain plugins like tech-radar & explore
• Having a omni search that searches both Backstage and documents in Notion
• Listing a section of Notion pages in Backstage like a TOC. Perhaps an EntityPage based component that can be listed on Group or Component pages based on an attribute.

[erikvanbrakel]

Having a omni search that searches both Backstage and documents in Notion

I did a quick spike of this. The main issue is that by default you won't get any results when using the API. Each API token is linked to an 'integration'. To allow an integration to find, read and modify your pages you need to give explicit permission, for every page individually. As far as I can tell there's no option to automatically make every new page available to certain integrations.

[andrewthauer]

Hmm, we use glean which is like an omni search over a bunch of tools. It can index pages in Notion, but I'm not sure exactly how. I suspect there is some other automation or API that adds the integration to pages automatically so that they can be indexed more broadly. But that's just a guess. Someone from Notion could probably provide some guidance here.

[ahmadassaf]

I came here as I was almost looking to implement a bespoke solution for this until I realised we have a backstage instance spun up and starting searching. I have done something using Streamlit but the issue I hit was the limitation of the Python Notion markdown converter in rendering different page items. Having seen some of the JS based alternatives like notion-to-md or react-notion It seems that backstage can be a good home for this idea!

To answer some of the concerns above from my knowledge:

The main issue is that by default you won't get any results when using the API. Each API token is linked to an 'integration'. If you have all your docs under a parent page and having the integration enabled at the parent level then it will get inherited to all child pages. So you can have a parent "wiki" page and that's it. For us; we have all our docs in a database actually; this allow us to annotate docs with properties and then enabling the integration at the database level is sufficient

You then need two main components; one component to fetch the documents from that database (we have created a new mirror checkbox property that will only show documents that have been marked as such in the mirrored solution (Streamlit for now)) and a renderer that will take the page and fetch the markdown

This is how it looks now in Streamlit! but will have a look on how to do this in Backstage

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.