Documentation Components for mantic UI

mantic UI Documentation components for Angular

Requires @mantic-ui/angular

Work-In-Progress

Currently we are heavily working to get all components and features implemented.

To support us, fork us at github

Documentation

Check out the documentation

mantic-sync-examples CLI

This package ships a small command that keeps the code shown for an <m-example> in sync with its live example markup, so you only ever write an example once.

For every <m-example> that references a code field, the command takes everything inside the <m-example> (except <m-example-code> elements and anything marked m-doc-ignore), normalises its indentation and writes it into that field's template literal in the component .ts file that owns the template.

A field can be referenced in two ways:

<!-- 1. via an <m-example-code> child -->
<m-example header="Checkbox" description="A standard checkbox">
    <m-checkbox name="example">Make my profile visible</m-checkbox>
    <m-example-code [code]="standardCode" />
</m-example>

<!-- 2. via a [code] attribute on <m-example> itself -->
<m-example header="Read-only" description="A checkbox can be read-only" [code]="readonlyCode">
    <m-checkbox readonly>Read Only</m-checkbox>
</m-example>

// checkbox.component.ts — updated in place
public standardCode = `<m-checkbox name="example">Make my profile visible</m-checkbox>`;
public readonlyCode = `<m-checkbox readonly>Read Only</m-checkbox>`;

Excluding parts of an example

Two marker attributes — backed by the empty DocIgnoreDirective and DocIgnoreContentDirective exported from this package — let you shape what gets extracted. They have no runtime behaviour; they exist so the markers are type-checked and autocompleted in templates. The CLI also matches them as plain text, so they work even where the directive is not imported.

m-doc-ignore — drop the whole element (handy for documentation notes that are not part of the example itself):

<m-example header="Page Headers" [code]="headerCode">
    <m-info m-doc-ignore>Page headings are sized using rem.</m-info>
    <h1 m-header>First Header</h1>
</m-example>

// headerCode receives only `<h1 m-header>First Header</h1>` — the note is dropped.

m-doc-ignore-content — keep the element but drop its content, collapsing it to a self-closing tag (handy when the inner text is noise):

<m-toggle [(checked)]="readonly" m-doc-ignore-content>Read Only</m-toggle>

// extracted as: <m-toggle [(checked)]="readonly" />

Usage

Run it from any project that depends on @mantic-ui/angular-doc:

# whole project (current directory), a folder, or a single file
npx mantic-sync-examples
npx mantic-sync-examples src/app/examples
npx mantic-sync-examples src/app/examples/checkbox/checkbox.component.html

| Option | Description | | --- | --- | | --check | Don't write; exit 1 if any field is out of date (use in CI). | | --dry-run | Print what would change without writing. | | -v, --verbose | Log every example, including unchanged and skipped ones. | | -q, --quiet | Only print warnings and the final summary. | | -h, --help | Show help. |

What is skipped

• Blocks with more than one <m-example-code [code]> (ambiguous which code maps where).
• Blocks that mix both mechanisms (a [code] attribute and an <m-example-code> child).
• A lone <m-example-code> whose [languages] excludes html (e.g. a ts snippet).
• A [code] bound to an expression rather than a plain field (e.g. [code]="layout | json").
• A field referenced by several <m-example> blocks with different content (a template bug — reported as a conflict).