Connected sources

Import Notion pages, GitHub repositories, docs sites and websites, and keep them current.

Open Knowledge, press Add, then Add content. The Sources list has Notion, GitHub, Docs site and Website.

Only admins and owners can open a source. Everyone else sees Admin access required. See roles.

Refresh and limits

• A refresh runs beside the reply. The reply uses what is indexed at that moment, and the next reply gets the changes.
• The library sync button has the tooltip Pull fresh copies from GitHub and Notion, or names just the one the library holds. It reads every file in every repository and docs site again, and pulls every Notion page again while Notion is connected.
• Sync now also reads every file, not just the ones that changed. Pressed during a sync, either button runs once that sync finishes, and so does a push.
• Titles come from a file’s frontmatter title, then its first heading, then its filename. It appears once the library holds a GitHub document, or a Notion page with Notion still connected.
• A repository or docs site whose last sync failed shows up under Needs fixing on the Dashboard as owner/repo is not syncing.

Notion

A refresh pulls every imported page again. It does not add new pages or new sub-pages. Import those.

Choose pages on the Workspace row reopens Notion’s consent screen, where you can share more pages with Median.

Disconnect asks Disconnect Notion? and keeps every imported document. Refreshes stop.

A connect link works once, for 15 minutes. After that, the return from Notion lands on a page that reads “This connection link has expired or was already used. Start again from Median.”

A failed page shows Failed in the library. The reason and Try again are on the document page.

GitHub

Median reads repositories through its GitHub app. You pick which repositories the app can see during the install on GitHub.

• Connect another under Accounts adds a second GitHub account or organization. The account menu in the repository picker has Connect another account too.
• The picker lists recently active repositories. Type a full owner/repo to reach one the list does not show.
• Missing a repository? Add access on GitHub opens the app’s settings on GitHub.
• One repository can be added more than once with different folders. The same repository and folder twice returns “That repository is already connected.”

What a sync takes

• A sync compares every file with the last sync. Unchanged files are skipped. Changed files are indexed again.
• A file deleted from the repository leaves the library.
• A new file joins the library folder its neighbours in the repository are in.
• Markdown files over 900 KB are skipped.
• Documents whose indexing failed are retried on every sync.
• Synced documents are edited in the repository. The document page shows a Read only badge with the tooltip “Edit this document in its source repository.”

Repository rows

Each row shows owner/repo, the folder and branch when set, and a status line.

Disconnect on an account removes every repository and docs site read through it, and their documents. Uninstalling the app on GitHub, or taking a repository’s access away there, does the same.

Sync errors

A sync that runs longer than 10 minutes is treated as stuck. The next sync takes over.

API specs

Repositories and docs sites turn OpenAPI specs into documents. Each endpoint document has Parameters, Request body, Responses and a curl command under Example request. The overview document lists the version, Base URL, Authentication and every endpoint.

Each spec can also go on your site as an API reference.

A file is read as a spec when all three tests pass:

A file that fails the contents test is ignored.

Specs must sit under the synced folder. A docs site also takes specs its config names, wherever they sit.

Docs sites

A docs site is a GitHub repository read through its framework’s config. The config sets which files are pages and the address each page publishes at. It uses the same GitHub accounts as the GitHub source.

Open Docs site and press Add docs site. The dialog has three steps.

A Blume or Docusaurus config that names its site fills Published at for you.

• index and README files publish at their folder’s route, except on Mintlify.
• A route prefix is not added twice when Published at already ends with it.
• When a repository holds several configs, GitBook is tried last.
• Median reads configs as text and does not run them. Check the three sample addresses before you add the site.

The site row shows the framework, the content folder and the branch, with the same status line and buttons as a repository row. Sync now on a docs site reads the config again even when the branch has not changed. Unchanged files are still skipped. Every sync that finds the repository changed reads the config again too, so a moved docs folder follows.

Websites

Websites need a paid plan. Without one the page shows “Available on Standard and Pro.” See plans.

• The crawl stays under the address you give. example.com/docs does not read example.com/blog.
• It reads the site’s sitemap and follows links. PDFs are read too.
• Each scraped page is charged in credits. A crawl stops at 500 pages, or sooner when credits run short.
• Each page becomes a document linked to the address it was scraped from.

A running crawl opens into three stages.

• Nothing refreshes on a schedule. Press Re-scrape when the site changes.
• A first crawl may use copies up to 2 days old. A re-scrape, or a new crawl of an address you scraped before, fetches live pages.
• The list shows the 20 most recent crawls.

Other failures say to try again later.

From the API

Full schemas are in the management API reference.