@fsegurai/ngx-shared-docs is an Angular library that combines...

@fsegurai/ngx-shared-docs is a modern Angular library providing reusable components, directives, pipes, and utilities for documentation sites and developer portals. It is built with Angular v20+, embracing signals, standalone components, and the latest best practices for performance and maintainability.

Table of Contents

• Features
• Library Structure
  • Components
  • Constants
  • Directives
  • Icons
  • Interfaces
  • Pipes
  • Providers
  • Services
  • Styles
  • Types
  • Utils
• Installation
• Usage
  • Basic Usage
• Development Guidelines
• Demo
• Contributing
• License

---

Features

• Reusable UI Components: Banner, cookie popup, clipboard button, icon, select, table of contents (TOC) navigation, doc viewer, and more.
• Directives: Click outside, and external link.
• Pipes: Common pipes for documentation needs.
• Providers & Services: Content loader, markdown, local storage, anchor navigation, raw HTTP loader.
• Utilities: Device detection, analytics, navigation, markdown factory, URL helpers.
• Styles: SCSS partials for theming, resets, typography, and component styles.
• SVG Icons: Ready-to-use icons for documentation UIs.

---

Library Structure

The @fsegurai/ngx-shared-docs library is organized into the following categories:

Components

Reusable UI components for building documentation sites:

• ClipboardButton: Button to copy text to clipboard.
• CookiePopup: Cookie consent popup.
• DocsViewer: Renders documentation content.
• Icon: SVG icon renderer.
• Select: Custom select dropdown.
• TableOfContents: Navigation for table of contents.
• Tooltip: Tooltip component.
• TopLevelBanner: Displays a banner at the top of the page.

Constants

Predefined constants for consistent usage:

• StorageKeys: Keys for local storage management.

Directives

Custom directives to enhance functionality:

• ClickOutsideDirective: Detects clicks outside an element.
• ExternalLinkDirective: Marks links as external.

Icons

SVG icons for documentation UIs:

• chevron-down.svg
• chevron-up.svg
• discord.svg
• github.svg
• youtube.svg

Interfaces

Type definitions for structured data:

• DocContent: Interface for documentation content.
• DocsContentLoader: Interface for content loader.
• Languages: Supported languages.
• Select: Select component options.
• TableOfContentsItem: Table of contents structure.
• Themes: Theme definitions.

Pipes

Reusable pipes for transforming data:

• Various pipes for formatting and transforming documentation data.

Providers

Dependency injection providers:

• DocsContentLoader: Loads documentation content.
• LocalStorage: Manages local storage.
• Markdown: Renders Markdown using its respective configuration and specified extensions.
• Window: Provides window-related utilities.

Services

Singleton services for application logic:

• AnchorService: Handles anchor navigation.
• HttpRawLoaderService: Loads raw HTTP content.
• TableOfContentsLoaderService: Loads table of contents.

Styles

SCSS partials for theming and styling:

• _api-item-label.scss
• _button.scss
• _colors.scss
• _media-queries.scss
• _resets.scss
• _typography.scss
• _utils.scss
• _z-index.scss
• global-styles.scss
• components/: Component-specific styles.
• docs/: Documentation-specific styles.
• themes/: Theme management styles.

Types

Type definitions for structured data:

• SelectOptionValue: Type for select options.

Utils

Utility functions for common tasks:

• animations.utils.ts: Animation utilities.
• device.utils.ts: Device detection utilities.
• html-sanitizer.utils.ts: HTML sanitizer utilities.
• markdown.utils.ts: Markdown rendering utilities.
• markdown-factory.utils.ts: Markdown generation helpers.
• navigation.utils.ts: Navigation helpers.
• url.utils.ts: URL manipulation utilities.

---

Installation

Install the library via npm:

npm install @fsegurai/ngx-shared-docs --save

Usage

Basic Usage

All components are standalone and use signals for state management. Import them directly in your Angular app:

import {TopLevelBannerComponent, ClipboardButtonComponent} from '@fsegurai/ngx-shared-docs/components';

@Component({
    selector: 'app-root',
    imports: [TopLevelBannerComponent, ClipboardButtonComponent],
    template: `
    <ngx-docs-top-level-banner text="Welcome to NGX Shared Docs!" />
    <ngx-docs-clipboard-button [text]="'Copy this text!'" />
  `,
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AppComponent {
}

---

Development Guidelines

This section outlines the best practices and coding standards followed in this library to ensure maintainability, performance, and modern Angular paradigms.

Angular Version

This library is built with Angular v20+ and leverages the latest features, including:

• Signals for reactive state management.
• Standalone Components for streamlined architecture.
• Native Control Flow for intuitive template logic.

Coding Standards

• TypeScript:
  • Use strict type checking.
  • Prefer type inference when the type is obvious.
  • Avoid the any type; use unknown when type is uncertain.
• Angular:
  • Always use standalone components over NgModules.
  • Use signals for state management.
  • Implement lazy loading for feature routes.
  • Use NgOptimizedImage for all static images.

Components

• Keep components small and focused on a single responsibility.
• Use input() signals and output() functions instead of decorators.
• Use computed() for derived state.
• Set changeDetection: ChangeDetectionStrategy.OnPush in @Component decorator.
• Prefer inline templates for small components.
• Prefer Reactive forms instead of Template-driven ones.

Templates

• Keep templates simple and avoid complex logic.
• Use native control flow (@if, @for, @switch) instead of *ngIf, *ngFor, *ngSwitch.
• Use the async pipe to handle observables.
• Use built-in pipes and import pipes when being used in a template.

Services

• Design services around a single responsibility.
• Use the providedIn: 'root' option for singleton services.
• Use the inject() function instead of constructor injection.

State Management

• Use signals for the local component state.
• Use computed() for derived state.
• Keep state transformations pure and predictable.

Styles

• Use SCSS partials for theming and styling.
• Follow the Angular Style Guide for consistent naming and structure.

For more details, refer to the Angular Style Guide.

---

Demo

See the components in action: Demo

To run the demo locally:

git clone https://github.com/fsegurai/ngx-shared-docs.git
bun install
bun start

The app will be served at http://localhost:4200.

Contributing

Contributions are welcome! Please follow the Angular Style Guide and use signals, standalone components, and the latest Angular features.

License

Licensed under MIT.