Installation

NgDoc is just a library, so first you need to create an Angular application that will be used to display documentation, it can be a separate application or an existing one.

When you install NgDoc, it will be integrated into the build process of your application, and will generate pages and components based on you code, that can be used in your application to display documentation.

Automatic (recommended)

To install the NgDoc, you can use the command below. This command will automatically install and add the library to your project, and configure it.

TypeScript may display an error for the @ng-doc/generated path in your code editor if you are using the library for the first time. Files for the @ng-doc/generated path will be generated automatically when you run your application, so please disregard any errors related to it.

ng add @ng-doc/add

By default, NgDoc uses your project's sourceRoot as the directory where you should create documentation, you can always change this, see the Configuration article for more details

Manual

Install the NgDoc via npm

npm i @ng-doc/{core,builder,ui-kit,app}

Adding builders

First of all you need to add builders from NgDoc library to your application, replace application and dev-server builders for build and serve targets with alternatives from the NgDoc as shown in the example below

{
  "projects": {
    "my-project": {
      "architect": {
        "build": {
          "builder": "@ng-doc/builder:application"
        },
        "serve": {
          "builder": "@ng-doc/builder:dev-server"
        }
      }
    }
  }
}

Importing styles

You will also need to import the global styles provided by the library by adding them to your styles array.

{
  "projects": {
    "my-project": {
      "architect": {
        "build": {
          "options": {
            "styles": ["node_modules/@ng-doc/app/styles/global.css"]
          }
        }
      }
    }
  }
}

Adding ng-doc folder to gitignore

ng-doc folder contains generated NgDoc files, you need to add it to your .gitignore, because NgDoc regenerates them every time the application is launched.

## NgDoc folder
/ng-doc

Adding assets

The NgDoc libraries come with assets that include various icons, fonts, themes, and other very useful things. You also need to add them to your application's assets.

{
  "projects": {
    "my-project": {
      "targets": {
        "build": {
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "node_modules/@ng-doc/ui-kit/assets",
                "output": "assets/ng-doc/ui-kit"
              },
              {
                "glob": "**/*",
                "input": "node_modules/@ng-doc/app/assets",
                "output": "assets/ng-doc/app"
              },
              {
                "glob": "**/*",
                "input": "ng-doc/<project-name>/assets",
                "output": "assets/ng-doc"
              }
            ]
          }
        }
      }
    }
  }
}

Updating tsconfig

NgDoc generates components for your documentation that you later need to import into the application, NgDoc also uses synthetic imports that you need to enable, to do this, edit the tsconfig.json of the existing application by adding the path to the generated files and allowSyntheticDefaultImports option.

TypeScript may display an error for the @ng-doc/generated path in your code editor if you are using the library for the first time. Files for the @ng-doc/generated path will be generated automatically when you run your application, so please disregard any errors related to it.

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "paths": {
      "@ng-doc/generated": ["ng-doc/<project-name>/index.ts"],
      "@ng-doc/generated/*": ["ng-doc/<project-name>/*"]
    }
  }
}

Configuring application

Provide default configuration for the documentation app.

import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
import { enableProdMode } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideAnimations } from '@angular/platform-browser/animations';
import { provideRouter, withInMemoryScrolling } from '@angular/router';
import {
  NG_DOC_DEFAULT_PAGE_PROCESSORS,
  NG_DOC_DEFAULT_PAGE_SKELETON,
  NgDocDefaultSearchEngine,
  provideNgDocApp,
  provideMainPageProcessor,
  providePageSkeleton,
  provideSearchEngine,
} from '@ng-doc/app';
import { NG_DOC_ROUTING, provideNgDocContext } from '@ng-doc/generated';

import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

bootstrapApplication(AppComponent, {
  providers: [
    // Provide context of the generated documentation
    provideNgDocContext(),
    // Provide default configuration for the documentation app
    provideNgDocApp(),
    provideSearchEngine(NgDocDefaultSearchEngine),
    providePageSkeleton(NG_DOC_DEFAULT_PAGE_SKELETON),
    provideMainPageProcessor(NG_DOC_DEFAULT_PAGE_PROCESSORS),
    // Provide animations
    provideAnimations(),
    // Provide 
HttpClient
 with interceptors (NgDoc uses interceptors)
    provideHttpClient(withInterceptorsFromDi()),
    // Add generated routes to the application
    provideRouter(
      NG_DOC_ROUTING,
      // Enable anchor scrolling
      withInMemoryScrolling({
        scrollPositionRestoration: 'enabled',
        anchorScrolling: 'enabled',
      }),
    ),
  ],
}).catch((err: unknown) => console.error(err));

Adding application layout

You will also need to add an application layer to your root AppComponent to display header and menu, to do this open your app.component.html file and add the following code to it

<ng-doc-root>
  <ng-doc-navbar [leftContent]="leftContent">
    <ng-template #leftContent>
      <h3 class="brand" style="margin: 0">MyDocs</h3>
    </ng-template>
  </ng-doc-navbar>
  <ng-doc-sidebar></ng-doc-sidebar>
  <router-outlet></router-outlet>
</ng-doc-root>