Skip to content

Latest commit

 

History

History
444 lines (307 loc) · 8.92 KB

components.mdx

File metadata and controls

444 lines (307 loc) · 8.92 KB
Raw
path title isInternal published
/components
Custom components and their usage
true
true

This guide helps authors and developers unify implementation by providing you with components, tokens and practices for our docsite.

Table of Contents

Best practices and gotchas

Translating markdown and HTML components into human-usable formatting can be scary. Follow these best practices to have a better experience:

  • Line breaks to separate HTML-style tags in React components from other types of content. For example:
  <Callout intent="info">
  <CalloutTitle>CALLOUT-TITLE</CalloutTitle>
  <CalloutDescription>

CALLOUT CONTENT.

  </CalloutDescription>
</Callout>

  • Left-justify text content inside callouts

    As pictured above. Callout contents do not respect markdown unless they are left-justified.

  • Line breaks after every component

    Separate headers, components, and other formatting with a paragraph break. This ensures the text formats correctly. Don't worry about inline links, those don't mess up any formatting.

# EXAMPLE HEADER
< -- this line deliberately left blank -- >
Content content.

Formatting callouts

You can put code samples and markdown into callouts in one of two ways.

Use a code block:

<CalloutTitle><code>more_code</code></CalloutTitle>

Or insert blank lines above and below where you want to use the markdown:

<Callout intent="info">
  <CalloutTitle>

`more_code`

  </CalloutTitle>
  <CalloutDescription>

`even_more_code`

  </CalloutDescription>
</Callout>

Different types of callouts

There are four different types of callouts:

<Callout intent="info"> (blue)

<Callout intent="alert"> (yellow)

<Callout intent="warning"> (red)

<Callout intent="primary"> (green)

Components

Learn more

Single

Learn more: Single link

<CodeTabs defaultValue="text" values={[ { label: 'Single Learn More', value: 'text', }, ] }> 

<LearnMore>

Learn more: [Single link](/foobar)

</LearnMore>

Multiple

Learn more:

<CodeTabs defaultValue="LearnMore" values={[ { label: 'Multiple Learn More', value: 'LearnMore', }, ] }> 

<LearnMore>

Learn more:
  * [This is an internal link](/foobar)
  * [External link](http://reactjunkie.com)
  * [Another internal link](/foobar)

</LearnMore>

Using Additional Text

Some lead text describing the links.

<CodeTabs defaultValue="LearnMore" values={[ { label: 'Using Additional Text', value: 'LearnMore', }, ] }> 

<LearnMore>

Some lead text describing the links.<br/><br/>

  * [This is an internal link](/foobar)
  * [External link](http://reactjunkie.com)
  * [Another internal link](/foobar)

</LearnMore>

Details

The docs site supports a details or "disclosure" component to expand/collapse information.

Here are some expanded details

<CodeTabs defaultValue="" values={[ { label: 'Details', value: 'Details', }, ] }>

<Details summary="Click to open more information">

Here are some expanded details

</Details>

Details may also be set to be open by default

This details is open by default

<CodeTabs defaultValue="" values={[ { label: 'Details', value: 'Details', }, ] }>

<Details open summary="Click to open more information">

This details is open by default

</Details>

Image

The docs site supports PNGs and GIFs. Just use Markdown images. Put the images in /src/content/images. In your Markdown, the path to the image is relative to that directory.

Some caption

<CodeTabs defaultValue="" values={[ { label: 'Image', value: 'Image', }, ] }>

![Some caption](data-export.png)

Callout

Include a blank line between the opening and closing <CalloutDescription> tags and the content. Do not indent any lines.

Primary

Adding users to LaunchDarkly

You do not have to send users to LaunchDarkly in advance. Check out this page. You can target them with feature flags have LaunchDarkly accounts of their own. Users appear in the Users dashboard automatically after they encounter feature flags.

Alert

Adding users to LaunchDarkly

You do not have to send users to LaunchDarkly in advance. Check out this page. You can target them with feature flags have LaunchDarkly accounts of their own. Users appear in the Users dashboard automatically after they encounter feature flags.

Warning

Adding users to LaunchDarkly

You do not have to send users to LaunchDarkly in advance. Check out this page. You can target them with feature flags have LaunchDarkly accounts of their own. Users appear in the Users dashboard automatically after they encounter feature flags.

Info

Adding users to LaunchDarkly

You do not have to send users to LaunchDarkly in advance. Check out this page. You can target them with feature flags have LaunchDarkly accounts of their own. Users appear in the Users dashboard automatically after they encounter feature flags.

<CodeTabs defaultValue="Callout" values={[ { label: 'Callout', value: 'Callout', }, ] }> 

<Callout intent="primary"> <!-- OR alert, warning, info -->
  <CalloutTitle>Adding users to LaunchDarkly</CalloutTitle>
  <CalloutDescription>

You do not have to send users to LaunchDarkly in advance. <a href="">Check out this page</a>. You can target them
with feature flags have LaunchDarkly accounts of their own. Users appear in the Users dashboard automatically after they
encounter feature flags.

  </CalloutDescription>
</Callout>

Code samples

  1. Write code block as markdown as usual.
  2. Add a CodeTabs component with a default value (which will be the first tab shown) and a values array of objects with a label and value.
  3. Each CodeTabItem will be one of the tabs

<CodeTabs defaultValue="code" values={[ { label: 'Code snippet', value: 'code', }, ] }> 

<CodeTabs
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'Python', value: 'py', },
    { label: 'Java', value: 'java', },
  ]
}>

    <CodeTabItem value="js">

    ```js
    function helloWorld() {
      console.log('Hello, world!');
    }
    ```

    </CodeTabItem>
    <CodeTabItem value="py">

    ```py
    def hello_world():
      print 'Hello, world!'
    ```

    </CodeTabItem>
    <CodeTabItem value="java">

    ```java
    class HelloWorld {
      public static void main(String args[]) {
        System.out.println("Hello, World");
      }
    }
    ```

    </CodeTabItem>

</CodeTabs>

Tables

Markdown tables are hard to read in text editors and easy to break. We built our own table component to use instead. It's much like an HTML table. When content in a table cell is left-justified, and bracketed by empty lines, you can use HTML tags in it.

<CodeTabs defaultValue="Table" values={[ { label: 'Table', value: 'Table', }, ] }> 

<Table>
  <TableHeader>
    <TableHeadCell>Name of column 1</TableHeadCell>
    <TableHeadCell>Name of column 2</TableHeadCell>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Column 1 Cell 1</TableCell>
      <TableCell>Column 1 Cell 2</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>

Column 2 Cell 1 <a href="example.com">with a link in it</a>.

      </TableCell>
      <TableCell>Column 2 Cell 2</TableCell>
    </TableRow>
  </TableBody>
</Table>