Star

MIT License
Copyright © 2020
CONNECT-platform

linkRecipe: Custom Search API

For this recipe, we're going to assume that we've got a nice search API that gives you a JSON array of URLs of matching documentation pages, based on a given query, and now we want to use it instead of the GitHub search for our docs.

We are assuming that the API, when requested with:

1linkcurl https://my-search.cloud?q=whatever

would respond with something like:

1link{

2link "results": [

3link "https://johndoe.github.io/my-project/",

4link "https://johndoe.github.io/my-project/docs/stuff",

5link "https://johndoe.github.io/my-project/docs/whatever/overview"

6link ]

7link}


linkStep 1: The Search Component

Lets create a search component in .codedoc/content/my-search.tsx:

.codedoc/content/my-search.tsx
1linkimport { ajax } from 'rxjs/ajax';

2linkimport { Subject, of } from 'rxjs';

3linkimport { switchMap, map, catchError, share } from 'rxjs/operators';

4linkimport { RendererLike, ComponentThis } from '@connectv/html';

5linkimport { transport } from '@connectv/sdh/transport';

6linkimport { ToCSearchBtn } from '@codedoc/core/components';

7link

8link

9linkexport function MySearch(this: ComponentThis, options: SearchOptions, renderer: RendererLike<any, any>) {

10link const query = new Subject();

11link const prefix = 'https://johndoe.github.io/my-project';

12link

13link const results = query.pipe(

14link switchMap(q =>

15link ajax.getJSON(

16link `https://my-search.cloud?q=${encodeURIComponent(q)}`

17link ).pipe(catchError(() => of(undefined))) // --> no sweat in case of error

18link ),

19link map(res =>

20link (res.results || [])

21link .map(url => url.substr(prefix.length)) // --> returned URLs must be relative to domain root

22link ),

23link share(),

24link );

25link

26link return <ToCSearchBtn label="Search via my-search ..." query={query} results={results}/>;

27link}

28link

29link

30linkexport const MySearch$ = /*#__PURE__*/transport(MySearch);


touch_app NOTE

Note that although we have defined the component MySearch, we also export a transported version of it named MySearch$. The reason is MySearch is a client-side component, i.e. it should be rendered and bound on the browser. However, we want to feed it to the rest of our layout components on the server-side, i.e. when we are building the HTML files. MySearch$ basically acts as a placeholder for MySearch in server-side code, allowing you to include it where you need it. When included, it will cause the code for the client-side component, i.e. MySearch, to be included in codedoc bundle, alongside an initialization script that would render MySearch in place of the placeholder on the browser.

Learn More

linkStep 2: Use MySearch

Now lets configure our ToC to use MySearch$ instead of the default GithubSearch$ component. For that purpose, we just need to modify .codedoc/content/index.tsx:

.codedoc/content/index.tsx
1linkimport { RendererLike } from '@connectv/html';

2linkimport { File } from 'rxline/fs';

3linkimport { Page, Meta, ContentNav, Fonts, ToC } from '@codedoc/core/components';

4link

5linkimport { config } from '../config';

6linkimport { Header } from './header';

7linkimport { Footer } from './footer';

8linkimport { MySearch$ } from './my-search'; // --> import the component

9link

10link

11linkexport function content(_content: HTMLElement, toc: HTMLElement, renderer: RendererLike<any, any>, file: File<string>) {

12link return (

13link <Page title={config.page.title.extractor(_content, config, file)}

14link favicon={config.page.favicon}

15link meta={<Meta {...config.page.meta}/>}

16link fonts={<Fonts {...config.page.fonts}/>}

17link

18link scripts={config.page.scripts}

19link stylesheets={config.page.stylesheets}

20link

21link header={<Header {...config}/>}

22link footer={<Footer {...config}/>}

23link toc={

24link <ToC search={<MySearch$/>}>{toc}</ToC> // --> give it to ToC for search

25link }>

26link {_content}

27link <ContentNav content={_content}/>

28link </Page>

29link )

30link}

Recipe: Custom Search APIStep 1: The Search ComponentStep 2: Use MySearch

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right