MIT License
Copyright © 2020

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:


would respond with something like:


2link$ "results": [

3link$ "",

4link$ "",

5link$ ""

6link$ ]


linkStep 1: The Search Component

Lets create a search component in .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';



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

10link const query = new Subject();

11link const prefix = '';


13link const results = query.pipe(

14link switchMap(q =>

15link ajax.getJSON(

16link `${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 );


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




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:

1linkimport { RendererLike } from '@connectv/html';

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

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


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

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

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

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



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

12link return (

13link <Page title={, config, file)}

14link favicon={}

15link meta={<Meta {}/>}

16link fonts={<Fonts {}/>}


18link scripts={}

19link stylesheets={}


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 )


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

Home Overview CLI Theme

Code Featureschevron_right

Images & Assets