angular-documentation-ui
TypeScript icon, indicating that this package has built-in type declarations

0.9.164 • Public • Published

This library provides a few UI components to help you to create a documentation website.

demo

Table of Contents

Installation

  1. Install angular-documentation-ui@latest
# For npm 7+, you need to add --legacy-peer-deps

npm i angular-documentation-ui@latest
  1. Install the @fortawesome/angular-fontawesome, ngx-highlightjs according to the compatibility table
# For npm 7+, you need to add --legacy-peer-deps

npm install @fortawesome/angular-fontawesome @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons ngx-highlightjs

Compatibility table

  • This library supports Angular 12.x, 13.x, 14.x, 15.x
Angular angular-documentation-ui ngx-highlightjs @fortawesome/angular-fontawesome @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons
12.x 0.9.x ^6.1.3 ^0.9.0 ^1.2.35 ^5.15.3
13.x 0.9.x ^6.1.3 ^0.9.0 ^1.2.35 ^5.15.3
14.x 0.9.x ^7.0.1 ^0.10.0 ^1.2.36 ^5.15.4
15.x 0.9.x ^7.0.1 ^0.10.0 ^1.2.36 ^5.15.4
16.x 0.9.x ^10.0.0 ^0.14.1 ^6.5.1 ^6.5.1
17.x 0.9.x ^10.0.0 ^0.14.1 ^6.5.1 ^6.5.1

Usage

To get up and running using Angular documentation UI with Angular follow the below steps:

For module-based applications

  1. Import this module to add.module.ts
import { DocumentationUiModule } from 'angular-documentation-ui';

@NgModule({
  declarations: [
    AppComponent,
    ...
  ],
  imports: [
    ...,
    DocumentationUiModule
  ],
  providers: [
    ...
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }
  1. Import the scss file to src/styles.scss
@import "../node_modules/angular-documentation-ui/styles/theme/index";
@import "../node_modules/angular-documentation-ui/styles/pages/index";
@import "../node_modules/angular-documentation-ui/styles/code/index";

body {
  background: var(--background-default);
}

For component-based applications

  1. Import this module to main.ts
import { DocumentationUiModule } from 'angular-documentation-ui';

bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(DocumentationUiModule)
    ],
});
  1. Import the scss file to src/styles.scss
@import "../node_modules/angular-documentation-ui/styles/theme/index";
@import "../node_modules/angular-documentation-ui/styles/pages/index";
@import "../node_modules/angular-documentation-ui/styles/code/index";

body {
  background: var(--background-default);
}

Demo site

UI components

1. Doc Reviewer

This component allows us to create the timeline to indicate the current section with the highlighted color.

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[titles] string[] Item names on the list
[sections] QueryList Instances of sections
[getIdFromTitle] function The function to create ID for title
[marginBotton] number The margin of the bottom (optional)

Usage

  1. Retrieve section elements and define section titles in your component
import { getIdFromTitle } from 'angular-documentation-ui';

export class MyComponent {
  getIdFromTitle = getIdFromTitle;
  
  sectionTitles = [
    "1",
    "2"
  ];
  
  @ViewChildren("section", {read: ElementRef}) sections: QueryList<ElementRef> | undefined;
}
  1. Update your template
<app-doc-reviewer-container
  [sections]="sections"
  [titles]="sectionTitles"
  [getIdFromTitle]="getIdFromTitle">
</app-doc-reviewer-container>

<div #section>
  <div class="title" [id]="getIdFromTitle(sectionTitles[0])" title>{{ sectionTitles[0] }}
  </div>  
</div>

<div #section>
  <div class="title" [id]="getIdFromTitle(sectionTitles[1])" title>{{ sectionTitles[1] }}
  </div>
</div>

2. Section Container

This component allows us to fold and unfold the content.

  • The following screnshot shows the demo of this component.
    • demo

Parameters

None.

Usage

  1. Update in your component
import { getIdFromTitle } from 'angular-documentation-ui';

export class MyComponent {
  getIdFromTitle = getIdFromTitle;
}
  1. Update your template
<app-section-container>
  <div class="title" [id]="getIdFromTitle(sectionTitles[0])" title>{{ sectionTitles[0] }}</div>
  <div class="description-container">
    <div class="item">
      content
    </div>
  </div>
</app-section-container>

3. Theme and Theme service

This component allows us to switch the theme for the UI component from this library.

  • The following screnshot shows the demo of this component.
    • light
      • demo
    • dark
      • demo

Parameters

None.

Usage

  1. Inject the Thene service to the App component
import { ThemeService } from 'angular-documentation-ui';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  constructor(private themeService: ThemeService) {
    let themeType = this.themeService.getCurrentThemeType();
    this.themeService.setThemeByThemeType(themeType);
  }
}
  1. Add the theme switcher to the template
<div class="theme-container">
  <app-theme></app-theme>
</div>

4. Navigation Button

This component allows us to navigate to the next page or the last page of the self-defined orders.

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[routeMap] map<string, string> The map to store pairs of URLs and string
[sideBarList] string[] Unique string for each route

Usage

  1. Define routeMap and sideBarList in your component
export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

export const RouteMap = new Map<string, RouteType>([
  ['/documents', RouteType.DOCUMENTS],
  ['/migrations', RouteType.MIGRATIONS],
  ['/breaking-changes', RouteType.BREAKING_CHANGE],
]);

export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  sideBarList = sideBarList;
  routeMap = RouteMap;
}
  1. Add the theme switcher to the template
<app-navigation-button-container 
  [routeMap]="routeMap"
  [sideBarList]="sideBarList">
</app-navigation-button-container>

5. Footer

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[routeMap] map<string, string> The map to store pairs of URLs and string
[sideBarList] string[] Unique string for each route
[showNavigationButton] boolean Show the navigation buttons or not
[externalLinkMap] map<string, string> The map to store pairs of titles and URLs

Usage

  1. Define routeMap and sideBarList in your component
export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

export const RouteMap = new Map<string, RouteType>([
  ['/documents', RouteType.DOCUMENTS],
  ['/migrations', RouteType.MIGRATIONS],
  ['/breaking-changes', RouteType.BREAKING_CHANGE],
]);

export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  sideBarList = sideBarList;
  routeMap = RouteMap;

  linkMap = new Map<string, string>([
    ["angular-doc-ui", "https://www.npmjs.com/package/angular-documentation-ui?activeTab=readme"]
  ]);
}
  1. Add the footer to the template
<app-footer-container 
  [routeMap]="routeMap"
  [sideBarList]="sideBarList"
  [showNavigationButton]="false"
  [externalLinkMap]="linkMap">
</app-footer-container>

5.1 Help Icon

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[tooltipsTemplate] TemplateRef null
[tooltipsWindowHeight] number The height of the tooltips window
[tooltipsWindowWidth] number The width of the tooltips window

Usage

  1. Define the content of the tooltips in your component
<ng-template #tooltipsContent>
  your content
</ng-template>
  1. Use the help-icon in the template
<app-help-icon
  [tooltipsTemplate]="tooltipsContent"
  [tooltipsWindowWidth]="180"
  [tooltipsWindowHeight]="180">
 </app-help-icon>

6. Navigation Button for Mobile

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[routeMap] map<string, string> The map to store pairs of URLs and string
[sideBarList] string[] Unique string for each route
[typeTitleMap] map<string, string> The map to store pairs of types and titles

Usage

  1. Define routeMap typeTitleMap, and sideBarList in your component
export enum RouteType {
  BREAKING_CHANGE = 'BREAKING_CHANGE',
  DOCUMENTS = 'DOCUMENTS',
  MIGRATIONS = 'MIGRATIONS',
}

export const RouteMap = new Map<string, RouteType>([
  ['/documents', RouteType.DOCUMENTS],
  ['/migrations', RouteType.MIGRATIONS],
  ['/breaking-changes', RouteType.BREAKING_CHANGE],
]);

export const TypeTitleMap = new Map<RouteType, string>([
  [RouteType.DOCUMENTS, 'About This Website'],
  [RouteType.MIGRATIONS, 'Upgrade to Angular 13'],
  [RouteType.BREAKING_CHANGE, 'Breaking Changes'],
  ]);

export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  sideBarList = sideBarList;
  routeMap = RouteMap;
}
  1. Add the nav-container to the template
<app-mobile-nav-container
  [routeMap]="routeMap"
  [sideBarList]="sideBarList"
  [typeTitleMap]="typeTitleMap">
</app-mobile-nav-container>

7. Code Container

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[key] string The key of the code snippet
[codeMap] map<string, Code> The map to store pairs of keys and code snippets

Usage

  1. Define the codeMap in your component
import { getIdFromTitle } from 'angular-documentation-ui';
import { Code, CodeLanguageType } from "angular-documentation-ui";

export class MyComponent {
  codeMap = new Map<string, Code>([
    ["instruction", {
      code: `
npx @angular/cli@13 new Angular13Project
      `,
      languages:[CodeLanguageType.html]
    }]
  ])
}
  1. Add the app-code-container to the template
<app-code-container key="instruction" [codeMap]="codeMap">
</app-code-container>

8. Side Bar

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[routeMap] map<string, string> The map to store pairs of URLs and string
[sideBarList] string[] Unique string for each route
[typeTitleMap] map<string, string> The map to store pairs of types and titles
[selectedRoute] string The default selected route
[showThemeButton] boolean Show the theme buttons or not
[showArrowButton] boolean Show the arrow buttons or not

Usage

  1. Define routeMap, TypeTitleMapand sideBarList in your component
export enum RouteType {
  BREAKING_CHANGE = 'BREAKING_CHANGE',
  DOCUMENTS = 'DOCUMENTS',
  MIGRATIONS = 'MIGRATIONS',
}

export const RouteMap = new Map<string, RouteType>([
  ['/documents', RouteType.DOCUMENTS],
  ['/migrations', RouteType.MIGRATIONS],
  ['/breaking-changes', RouteType.BREAKING_CHANGE],
]);

export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

export const TypeTitleMap = new Map<RouteType, string>([
  [RouteType.DOCUMENTS, 'About This Website'],
  [RouteType.MIGRATIONS, 'Upgrade to Angular 13'],
  [RouteType.BREAKING_CHANGE, 'Breaking Changes'],
  ]);

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  sideBarList = sideBarList;
  routeMap = RouteMap;
  typeTitleMap = TypeTitleMap;
}
  1. Add the app-side-bar-container to the template
<app-side-bar-container
  [routeMap]="routeMap"
  [sideBarList]="sideBarList"
  [typeTitleMap]="typeTitleMap"
  selectedRoute="DOCUMENTS">
  {{ customized content}}
</app-side-bar-container>

9. Navigation Button for Universal

  • It's the componnt combined app-side-bar-container and the app-mobile-nav-container

Parameters

Name Type Description
[routeMap] map<string, string> The map to store pairs of URLs and string
[sideBarList] string[] Unique string for each route
[typeTitleMap] map<string, string> The map to store pairs of types and titles
[selectedRoute] string The default selected route
[showThemeButtonForSideBar] boolean Show the theme buttons or not
[showArrowButtonForSideBar] boolean Show the arrow buttons or not

Usage

  1. Define routeMap, TypeTitleMapand sideBarList in your component
export enum RouteType {
  BREAKING_CHANGE = 'BREAKING_CHANGE',
  DOCUMENTS = 'DOCUMENTS',
  MIGRATIONS = 'MIGRATIONS',
}

export const RouteMap = new Map<string, RouteType>([
  ['/documents', RouteType.DOCUMENTS],
  ['/migrations', RouteType.MIGRATIONS],
  ['/breaking-changes', RouteType.BREAKING_CHANGE],
]);

export const sideBarList = [
  RouteType.DOCUMENTS,
  RouteType.MIGRATIONS,
  RouteType.BREAKING_CHANGE,
];

export const TypeTitleMap = new Map<RouteType, string>([
  [RouteType.DOCUMENTS, 'About This Website'],
  [RouteType.MIGRATIONS, 'Upgrade to Angular 13'],
  [RouteType.BREAKING_CHANGE, 'Breaking Changes'],
  ]);

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  sideBarList = sideBarList;
  routeMap = RouteMap;
  typeTitleMap = TypeTitleMap;
}
  1. Add the app-side-bar-container to the template
<lib-doc-nav-container
  [routeMap]="routeMap"
  [sideBarList]="sideBarList"
  [typeTitleMap]="typeTitleMap"
  selectedRoute="DOCUMENTS">
  {{ customized content}}
</lib-doc-nav-container>

10. Loading Indicator

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[detectNavigation] boolean Detect the changes of navigation or not

Usage

  • Update the template
<router-outlet></router-outlet>
<app-loading-indicator [detectNavigation]="true"></app-loading-indicator>

11. Tree View

  • The following screnshot shows the demo of this component.
    • demo

Parameters

Name Type Description
[root] AngularUiDocumentationTree Tree structure of the raw data
[searchValueSubject] BehaviorSubject BehaviorSubject for the search keyword
[isLoading] boolean (optional) To show the loading indicator or not
[indentLength] number (optional) The indent length
[indentPaddingLeft] number (optional) Tree left padding length

Usage

  1. Update the template
<app-angular-ui-documentation-tree
  [root]="root"
  [searchValueSubject]="searchValueSubject"
  [isLoading]="isLoading">
</app-angular-ui-documentation-tree>
  1. Define the HTTP clients
  • service
@Injectable({
  providedIn: 'root'
})
export class AngularSiteService {

  constructor(protected http: HttpClient) { }

  list(): Observable<AngularSite[]> {
    return this.http.get<AngularSite[]>('api/angular-site');
  }
}

@Injectable({
  providedIn: 'root'
})
export class AngularSiteTopicService {
  constructor(protected http: HttpClient) { }

  load(siteId: string): Observable<AngularSiteTopic[]> {
    return this.http.get<AngularSiteTopic[]>(`api/angular-site-topic?siteId=${siteId}`);
  }
}
  • data structure
export class AngularSite {
  id: string;
  name: string;
  url: string;
}

export class AngularSiteTopic {
  id: string;
  siteId: string;
  name: string;
  url: string;
}

export type HelpIconContentTreeRawaDataType = AngularSite | AngularSiteTopic;
  1. Update the component
export class AppComponent {
  root:  AngularUiDocumentationTree<HelpIconContentTreeRawaDataType> | null;
  isLoading: boolean = false;
  searchValueSubject = new BehaviorSubject<string | null>(null);

  depthApiLoadMap = new Map<number, (id?: string) => Observable<HelpIconContentTreeRawaDataType[]>>([
    [0, this.angularSiteService.list.bind(this.angularSiteService)],
    [1, (id) => this.angularSiteTopicService.load(id!)],
  ]);

  constructor(
    protected angularSiteService: AngularSiteService,
    protected angularSiteTopicService: AngularSiteTopicService,
    private angularUiDocumentationTreeService: AngularUiDocumentationTreeService<HelpIconContentTreeRawaDataType>
  ) {
    this.service.sideBarContainer$.subscribe(type => {
      this.currentSideBarContainerType = type;
    });

    this.isLoading = true;
    this.angularUiDocumentationTreeService.buildTree(
      "All Topics",  
      this.depthApiLoadMap
    ).subscribe((data: AngularUiDocumentationTree<HelpIconContentTreeRawaDataType>) => {
      this.root = data;
      this.isLoading =false;
    })
  }
}

Utilities

1. Google Analytics 4

Usage

  • Update the app.compnent.ts
export class AppComponent implements OnInit {
  ngOnInit(): void {
    updateGoogleAnalyticsId({{ your Google Analytics ID}});
  }
}

Package Sidebar

Install

npm i angular-documentation-ui

Weekly Downloads

79

Version

0.9.164

License

MIT

Unpacked Size

710 kB

Total Files

73

Last publish

Collaborators

  • jenhsuanhsieh