Compare commits

..

2 Commits

Author SHA1 Message Date
Peter White 651c72eb1c changeset 2026-11-18 22:47:48 +00:00
Peter White adbdd552ea Let browsers discover a published site's search via OpenSearch 2026-11-18 22:47:45 +00:00
6 changed files with 91 additions and 0 deletions
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Publish an OpenSearch description on every site so browsers can offer its search from the address bar.
@@ -0,0 +1,14 @@
import type { NextRequest } from 'next/server';
import { type RouteLayoutParams, getStaticSiteContext } from '@/app/utils';
import { serveOpenSearchDescription } from '@/routes/opensearch';
export const dynamic = 'force-static';
export async function GET(
_request: NextRequest,
{ params }: { params: Promise<RouteLayoutParams> }
) {
const { context } = await getStaticSiteContext(await params);
return serveOpenSearchDescription(context);
}
@@ -22,6 +22,7 @@ import { GITBOOK_API_PUBLIC_URL, GITBOOK_ASSETS_URL, GITBOOK_ICONS_URL } from '@
import { getResizedImageURL } from '@/lib/images';
import { removeTrailingSlash } from '@/lib/paths';
import { isSiteIndexable } from '@/lib/seo';
import { getOpenSearchURL } from '@/routes/opensearch';
// Pure trackers with no visitor-facing UI, safe to load after `load` + idle. Anything not
// listed (consent managers, chats, assistants…) keeps loading eagerly.
@@ -85,6 +86,12 @@ export async function SiteLayout(props: {
<>
{/* First in <body> so agents reading the HTML find it before the navigation. */}
<LLMsTxtDirective context={context} />
<link
rel="search"
type="application/opensearchdescription+xml"
href={getOpenSearchURL(context)}
title={context.site.title}
/>
<SiteLayoutClientContexts
contextId={context.contextId}
forcedTheme={
+1
View File
@@ -1009,6 +1009,7 @@ function encodePathInSiteContent(
case '~gitbook/embed/script.js':
case '~gitbook/embed/demo':
case '~gitbook/site-index':
case '~gitbook/opensearch.xml':
// LLMs.txt, sitemap, sitemap-pages and robots.txt are always static
// as they only depend on the site structure / pages.
return { pathname, routeType: 'static' };
@@ -0,0 +1,33 @@
import { describe, expect, it } from 'bun:test';
import { getOpenSearchURL, serveOpenSearchDescription } from './opensearch';
import type { GitBookSiteContext } from '@/lib/context';
import { createLinker } from '@/lib/links';
describe('OpenSearch description', () => {
const context = {
site: { title: 'R&D <Docs>' },
linker: createLinker({
host: 'docs.company.com',
siteBasePath: '/docs',
spaceBasePath: '/docs/v1',
}),
} as GitBookSiteContext;
it('is served from the site root for every variant', () => {
expect(getOpenSearchURL(context)).toBe(
'https://docs.company.com/docs/~gitbook/opensearch.xml'
);
});
it('searches the site root and escapes the title', async () => {
const response = serveOpenSearchDescription(context);
expect(response.headers.get('content-type')).toBe(
'application/opensearchdescription+xml; charset=utf-8'
);
const xml = await response.text();
expect(xml).toContain('<ShortName>R&amp;D &lt;Docs&gt;</ShortName>');
expect(xml).toContain('template="https://docs.company.com/docs?q={searchTerms}"');
});
});
+31
View File
@@ -0,0 +1,31 @@
import type { GitBookSiteContext } from '@/lib/context';
import { escapeHTML } from '@/lib/html';
/**
* Return the URL of the site's OpenSearch description, shared by every section and variant.
*/
export function getOpenSearchURL(context: GitBookSiteContext): string {
return context.linker.toAbsoluteURL(context.linker.toPathInSite('~gitbook/opensearch.xml'));
}
/**
* Serve an OpenSearch description so browsers can search the site from the address bar.
*/
export function serveOpenSearchDescription(context: GitBookSiteContext): Response {
const { linker, site } = context;
const title = escapeHTML(site.title);
const searchURL = escapeHTML(`${linker.toAbsoluteURL(linker.toPathInSite(''))}?q=`);
const xml = `<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>${title}</ShortName>
<Description>Search ${title}</Description>
<InputEncoding>UTF-8</InputEncoding>
<Url type="text/html" method="get" template="${searchURL}{searchTerms}"/>
</OpenSearchDescription>
`;
return new Response(xml, {
headers: { 'Content-Type': 'application/opensearchdescription+xml; charset=utf-8' },
});
}