#Markdown

Most of the GitHub flavoured markdown features are enabled, in addition there is syntax highlighting for code samples and images are supported. For a full list, there is the markdown features page.

#Linking design system pages

Use a simplified markdown syntax to link to pages, in order to prevent dead links. Just specify the top-navigation category and child category if present and the page title in the link syntax
[Icons](Components) or [Radio Button Form Field](Develop/Form).

#Handling spaces in titles

Due to limitations of the mdx parser, we need to replace spaces with + in the href part: [Help Text](Components/Input+Field).

#Linking a tab

Linking directly into tabs is possible by specifying the tab in the link description
[Button/Code](Components)

#Custom link text

Using a pipe to separate the page title, results in custom link text
[Custom link text|Button/Code](Components)

#Front matter

A a front matter part configuration part is required for every documentation page. This is a yaml object within a tripple-dash boundary.

---
isPublic: false
navigation: Develop
title: Example Code Documentation
tab: Code
terms:
  - Searchterm
---

#The global meta object

Parsed front matter including some enriched data:

#PropTable

Displays the contents of docgen in an interactive table. Here is the table of <PropTable /> itself.

{
 // Passing a boolean, generates a checkbox
 // Using the passed value as initial state
 checked: false,

 // Passing a string, generrates a text field
 // Using the passed value as initial state
 // Useful to override `ReactNode` and similar
 children: "Some text content",

 // Number works similar to string
 count: 20,

 // Array `number[]` and `string[]` are supported
 // Generate a select dropdown, the first value
 // is selected. If the prop is optional, an empty
 // first option is added automatically
 lineHeight: ["12", "18", "24"],

 // Null disables an automatically generated control
 checkbox: null,

 // Complex overrides
 // Useful for complex types
 // initialValue is optional. If present the
 // `text` part (string) of the options is expected
 icon: {
   initialValue: "filled hearts",
   options: [
     { text: "cart", value: <CartIcon /> },
     { text: "minus", value: <MinusIcon /> },
     { text: "filled heart", value: <HeartFilledIcon /> },
     { text: "plus", value: <PlusIcon /> },
     { text: "calendar", value: <CalendarIcon /> },
   ]
 },
}

<PropTable staticProps={{ name: "checkbox1" }}>
 <Checkbox />
</PropTable>

<PropTable
 staticProps={(setProp) => ({
   onChange: (event) => setProp("checked", event.target.checked),
 })}
>
 <Checkbox />
</PropTable>

// __docs__/button.mdx
import { PropTable } from "@tools/documentation-support";

<PropTable component={Button} />;

#Default value

Default values are not automatically guessed, but can be set in JSDOC by using the @defaultValue keyword.

Make sure the type of the value is correct and is wrapped in code ticks.`

export interface IAlertProps extends ComponentPropsWithRef<"div"> {
  /**
   * The variant of the alert
   * @defaultValue `"warning"`
   * */
  variant: AlertVariant;
}

#Hiding props

The easiest way is to not specify any JSDOC comment and use regular comments. In some case this is not possible, e.g. when extending. In this case the @ignore keyword may be used

export interface IIconButton extends ComponentPropsWithRef<"div"> {
  // this won't show up in PropTable
  internalStuff: boolean;

  /**
   * No children expeced
   * @ignore
   * */
  children?: null;
}

#Two way sync controls

In cases like form controls, sometimes a two way sync is desired, between the controls in the prop table and the control itself. This can be easily achieved by passing a function to staticProps, this gives access to the setProp(propName: string, value: unknown) dispatch method for the PropTableContext (internally used to store current props).

import { PropTable } from "@tools/documentation-support";
import { Checkbox } from "../checkbox.tsx";

// Two way syncing prop values

<PropTable
  docs={meta.docs.Checkbox}
  staticProps={(setProp) => ({
    onChange: (event) => {
      setProp("checked", event.target.checked);
    },
  })}
>
  <Checkbox />
</PropTable>

#ResponsiveFrame

An iframe that renders components. For style isolation in both directions, all component examples are rendered inside frames.

<ComponentFrame staticProps={{ name: "checkbox1" }}>
 <Checkbox />
</ComponentFrame>

import { ResponsiveFrame } from "@tools/documentation-support";
import { Button } from "../button.tsx";

<ResponsiveFrame>
  <Button />
</ResponsiveFrame>

#ComponentFrame

The same as ResponsiveFrame, but without all the borders and stuff around.

import { ComponentFrame } from "@tools/documentation-support";
import { Button } from "../button.tsx";

<ComponentFrame>
  <Button />
</ComponentFrame>

#Demos in mdx

Demos from the demo-studio integrate with the link syntax. This is useful to present alternative variants of the component. This generates a ResponsiveFrame and a code block. Under the hood, a custom webpack loader is used to achieve this.

### Dense Inline Button

The Button uses _minimal width_ on every screen size.

[DenseInlineButtonDemo](../button.demo.tsx)

#Seting frame props for demos

Setting ResponsiveFrame props for demos when rendered in documentation, with the setPresentationOptions() method

import { setPresentationOptions } from "@tools/documentation-support/demo";

export const DummyDemo = () => <div>hello demo</div>;

setPresentationOptions([DummyDemo], {
  noBreakpoints: true,
});

#Markdown Page Template

Note: By using the Package Generator this get's generated automatically for your component.

---
navigation: Develop
title: Example Code Documentation
docgen:
  - "../exampleComponent.tsx"
---

import { PropTable, ResponsiveFrame } from "@tools/documentation-support";
import { ExampleComponent } from "../exampleComponent.tsx";

## Example Code Documentation

Some lead text

### Props

<PropTable
  docs={meta.docs.ExampleComponent}
  controls={{
    children: "Some editable text",
  }}
>
  <ExampleComponent />
</PropTable>

### Variants

[ExapmleStateDemo](../exampleComponent.demo.tsx)

### Advanced variants

<ResponsiveFrame>
  <ExampleComponent variant="big" />
</ResponsiveFrame>

#Images

Images can be integrated by saving them in the directory applications/design-system/public/design/static/documentation.

To integrate them in your documentation, there is a special component you should use:

import { Image } from "@tools/documentation-support";

<Image
  src="/designsystem/static/documentation/ownership-overview.png"
  width="500"
  height="425"
  alt="overview of the monorepo structure"
/>;

It is very important to define width and height props - and the values for width/height must be half of the actual image size. So, if your image has the dimensions 900x500 pixels, then the props for width/height will be 450x250. This is needed for retina screens where the device-pixel-ratio is bigger than 1 - the image will be integrated in full resolution but only rendered half the size.

💡 All images will be uploaded to Akamai NetStorage and we use Image Manager to optimize them in Production!

#Dos And Don'ts

Use the DosAndDonts component to display dos and don'ts examples.

You can increase the block width by using the fullWidth property. Additionally the direction property can be used to display the items either vertically or horizontally.

import {
  DoOrDont,
  DoOrDontDescription,
  DosAndDonts,
  Image,
} from "@tools/documentation-support";

<DosAndDonts>
  <DoOrDont>
    <DoOrDontDescription variant="do">
      Explain why is the button disabled
    </DoOrDontDescription>
    <Image
      src="/designsystem/static/figma-graphics/button_do___do_example_do-f81ffbdff81ff81ffbdff80ff80fe007e007e007edf7e007e007e7f7e007e007.png"
      width="313"
      height="106"
      alt="Button do - Do example-do"
    />
  </DoOrDont>
  <DoOrDont>
    <DoOrDontDescription variant="dont">
      Without an explanation, the user doesn&apos;t know why they cannot use
      this feature.
    </DoOrDontDescription>
    <Image
      src="/designsystem/static/figma-graphics/button_dont___dont_example_dont-00037ffb7ffb7ffb7ffb5a5b400b400b400b7ff97ff87ff87ff00000fff8fffc.png"
      width="119"
      height="48"
      alt="Button dont - Dont example-dont"
    />
  </DoOrDont>
</DosAndDonts>;

Do

Explain why is the button disabled

Don't

Without an explanation, the user doesn't know why they cannot use this feature.

#Info Panel

Use the InfoPanel component to guide the user's attention to the displayed information.

import { InfoPanel } from "@tools/documentation-support";

<InfoPanel variant="warning">Some important information</InfoPanel>;