Pages and categories

The creation of pages and categories in the documentation is considered in this section.

Page

The page is a typescript file that has ng-doc.page.ts name and exports a configuration of type NgDocPage.

You can create a page by creating a new file in your pages directory (the app src folder by default) or by running the schematic command below (all available options you can find in the interface NgDocBuildPageSchema):

Remember that the schematic command is called for the current directory, to run it for another directory, you need to specify the path to it in the --path parameter of the command.

ng g @ng-doc/builder:page "Installation"

This entity must be exported from the file by default, otherwise NgDoc will not load it. Multiple exports from the entity are not supported

import { NgDocPage } from '@ng-doc/core';

const InstallationPage: NgDocPage = {
  title: 'Installation',
  mdFile: './index.md',
};

export default InstallationPage;

Page description

The description of the page can be added as a JSDoc comment in the page configuration file. It will be displayed below the page header and will be common to all tabs of the page if they are present.

You can use markdown in the description.

import { NgDocPage } from '@ng-doc/core';

/**
 * This page describes how to install the library.
 */
const InstallationPage: NgDocPage = {
  title: 'Installation',
  mdFile: './index.md',
};

export default InstallationPage;

Page tabs

The content of the page should be inside a markdown file specified in the mdFile property of the page configuration. You can also specify paths to multiple files, so NgDoc will display them as multiple tabs on the page.

Even when using tabs, you still need to use index.md, it will be used as the first tab and should not contain the route configuration. Therefore, if you navigate to the page, index.md will be displayed by default.

import { NgDocPage } from '@ng-doc/core';

const InstallationPage: NgDocPage = {
  title: 'Installation',
  mdFile: ['./index.md', './nx.md'],
};

export default InstallationPage;

The title, icon, route, and other parameters for a tab can be specified within the file itself using metadata (check the MarkdownEntry interface to see all available properties):

---
title: Nx
icon: Nx
route: nx
keyword: InstallationNxPage
---

## Running CLI commands

To run a CLI command, use the following command...

Category

Categories are used to structure your documentation and group pages. Every category is a typescript file that has ng-doc.category.ts name and exports a configuration of type NgDocCategory.

You can create a category by creating a new file in your categories directory (the app src folder by default) or by running the schematic command below (all available options you can find in the interface NgDocBuildCategorySchema):

Remember that the schematic command is called for the current directory, to run it for another directory, you need to specify the path to it in the --path parameter of the command.

ng g @ng-doc/builder:category "Getting Started"

This entity must be exported from the file by default, otherwise NgDoc will not load it. Multiple exports from the entity are not supported

import { NgDocCategory } from '@ng-doc/core';

const GettingStartedCategory: NgDocCategory = {
  title: 'Getting Started',
};

export default GettingStartedCategory;

Adding pages to a category

To add a page to a category, you can use the category field in the page configuration. Just import the category and put it in the category field, like this:

import { NgDocPage } from '@ng-doc/core';
import GettingStartedCategory from '../ng-doc.category';

const InstallationPage: NgDocPage = {
  title: 'Installation',
  mdFile: './index.md',
  category: GettingStartedCategory,
};

export default InstallationPage;

Adding status badge for a page

You can add a different statuses for a page to display them in the sidebar. To do this, you need to use @status tag in your page configuration file. The @status tag should contain the status color that starts with : and the status text. To see all available statuses, check the NgDocColor type.

import { NgDocPage } from '@ng-doc/core';

/**
 * @status:info NEW
 */
const InstallationPage: NgDocPage = {
  title: 'Installation',
  mdFile: ['./index.md', './nx.md'],
};

export default InstallationPage;