@component-catalog/core

ComponentCatalog is a Angular module to help creating a catalog of the application's components for documentation. Additional markdown documentation can be written for further documentation purposes.

Usage no npm install needed!

<script type="module">
  import componentCatalogCore from 'https://cdn.skypack.dev/@component-catalog/core';
</script>

README

ComponentCatalog

ComponentCatalog helps to create a visual overview of your Angular apps components. Additionally, a markdown-based documentation can be included. With ComponentCatalog you'll have all information (commonly referred to as style guide) in one place making it the ultimate tool for your designers and developers.

Usage

Installation

npm i @component-catalog/core

Create catalog app

Create a new application via Angular CLI:

ng generate application catalog --routing --style scss --skip-tests

Import ComponentCatalogModule

Import ComponentCatalogModule into the newly created catalog-app:

import { ComponentCatalogModule } from '@component-catalog/core';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    ComponentCatalogModule.forRoot(),
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {
}

Add routing

Within the newly created file app-routing.module.ts update the import of Angular's RouterModule to:

@NgModule({
  imports: [RouterModule.forRoot([{ path: '', pathMatch: 'full', redirectTo: 'component-catalog' }])],
  exports: [RouterModule],
})
export class AppRoutingModule {
}

Write demo components

Create the components

Within the catalog, only demo components are written. The demo components will use your application's components and add additional documentation.

Use the Angular CLI to create a new demo component within the catalog (make sure to execute the command within the catalog folder):

ng g c demo-button

Update the template

Within the template of the newly created demo-button, you can add your app's button and provide more information:

<app-button>demo-button works! as real component here!</app-button>

<h2>Additional information</h2>
<p>This is some additional information about your button.</p>

Update TypeScript

The next step is to open the TypeScript file of your created demo-button. Add the @ComponentCatalog decorator to the component's class:

@ComponentCatalog({ name: 'Button', group: 'Simple Components' })

The property name will be used as the name within the navigation. The property group will be used for grouping several components under the same label within the navigation.

Update app.module.ts

Finally, update the catalog's app.module.ts and add the demo-button as an entryComponents to the @NgModule decorator:

entryComponents: [
  DemoButtonComponent,
],

Write additional markdow documentation

If you want, you can write additional markdown documentation, which will be included into the final ComponentCatalog. Per default, all markdown files within a docs folder at the root of your project will be included. To group markdown files, they need to be enclosed within their own folder, e.g.:

docs
  |- colors
    |- Background Colors.md
    |- Foreground Colors.md
  |- animations
    |- Introduction.md
    |- General.md

Within the markdown files you can write any markdown you want. GFM-Syntax is supported as well. Code will be highlighted by PrismJS. Supported languages are:

  • Bash
  • PowerShell
  • CSS
  • HTML
  • Docker
  • JSON
  • LESS
  • SASS
  • SCSS
  • TypeScript
  • JavaScript

Start the catalog

ng serve catalog

Design Mockups

ComponentCatalog is a newly created project where a lot of ideas have not been implemented yet. In the meantime, enjoy some design mockups from kaeku. Additionally, feel free to submit ideas and bug reports!

Component Details