App providers and SSR APIs

The providers that configure the documentation application, and the APIs for server-side rendering. Add the providers to your application configuration (Installation [4. Add the providers]).

Providers

The routes of the site are in NG_DOC_ROUTING, also from @ng-doc/generated. The application also needs the Angular router and provideHttpClient(withInterceptorsFromDi()), because NgDoc registers an HTTP interceptor.

provideNgDocApp

provideNgDocApp(config?: NgDocApplicationConfig). See also NgDocApplicationConfig.

NgDocUiConfig has two fields. Set both when you pass uiKit:

The site uses the two scrolling options with the matching router options:

provideNgDocApp({
  contentAnchorScrolling: true,
  contentScrollPositionRestoration: 'enabled',
});

provideSearchEngine

provideSearchEngine(engine, ...args) creates the engine class with the given arguments. The default engine is NgDocDefaultSearchEngine, and its first argument is an NgDocDefaultSearchEngineOptions object:

The engine returns the matching guides first, then the matching API pages, each in order of relevance. Guides take up to half of limit, or more when fewer API pages match, and API pages fill the rest.

provideSearchEngine(NgDocDefaultSearchEngine, { limit: 20 });

To use another engine, extend NgDocSearchEngine and pass your class.

providePageSkeleton

providePageSkeleton(skeleton: NgDocPageSkeleton). There is no default skeleton: pass NG_DOC_DEFAULT_PAGE_SKELETON for the standard components, or your own object.

Leave a field out to remove that part of the page.

Page processors

provideMainPageProcessor(processors) registers the processors you pass. Pass NG_DOC_DEFAULT_PAGE_PROCESSORS for the standard ones, which render links, icons, heading anchors, callouts, tooltips, diagrams, code blocks, demos, demo panes, playgrounds, tabs, images and the members tables of API pages. providePageProcessor(processors) adds your own, which run after the main processors. Each processor is an NgDocPageProcessor:

provideTypeControl

provideTypeControl(type: string, control, options?) registers a playground control for inputs of the given type name.

Preload pages

A page's code and content load when the reader opens it. To have them ready before that, set NgDocPreloadingStrategy as the router's preloading strategy:

provideRouter(routes, withPreloading(NgDocPreloadingStrategy));

NgDoc then preloads a page when the reader points at, focuses or touches a link to it anywhere on the site: in the sidebar, the previous and next page links, the page content, the search results and the table of contents. After a guide renders, its previous and next guides are preloaded once the browser is idle. Each page is preloaded once, and only the pages the reader is about to open: the strategy never loads every page, as PreloadAllModules would. Nothing is preloaded on the server, when the reader has turned on data saving, or on a 2G connection. NgDocRoutePreloader also preloads a page on demand, with preload(url).

Without the strategy, pages still open without a blank page in between: the router keeps the current page on screen until the next page and its content have loaded.

Server-side rendering

Wrap the bootstrap function in main.server.ts:

import { bootstrapApplication, BootstrapContext } from '@angular/platform-browser';
import { withNgDocContentReady } from '@ng-doc/app';

import { App } from './app/app';
import { config } from './app/app.config.server';

const bootstrap = (context: BootstrapContext) => bootstrapApplication(App, config, context);

export default withNgDocContentReady(bootstrap);

Without it, the server can return a page before its content has loaded. Production builds and prerendering describes prerendering.