Adjust's SDK documentation is written using [GitHub-flavored markdown (GFM)](https://github.github.com/gfm/) enhanced with [MDX](https://mdxjs.com/) to add support for dynamic structural components.

> **Important**: All inline Markdown MUST conform to the GFM spec to avoid issues with localization.

This primer demonstrates the use of some of the custom features used in the Adjust SDK documentation.

* [Basic convention notes](#basic-convention-notes)
* [Code fences](#code-fences)
  * [Syntax highlighting](#syntax-highlighting)
* [Callouts](#callouts)
  * [Callout types](#callout-types)
* [Accordions](#accordions)
* [Content versions](#content-versions)
  * [SDK versions](#sdk-versions)
  * [API versions](#api-versions)
  * [Minor versions](#minor-versions)
* [Tabbed content](#tabbed-content)
* [Tables](#tables)

## Basic convention notes

Use the following conventions when contributing to the SDK documentation:

* Use hyphens (`-`) instead of asterisks (`*`) for unordered lists.
* Use asterisks (`**`) instead of underscores (`__`) to format **bold** text.
* User asterisks (`*`) instead of underscores (`_`) to format *italicized* text. 
* Use inline formatting for links (`[link-text](link-destination)`) rather than reference links.

## Code fences

This repository makes use of [expressive-code](https://expressive-code.com/) to render code blocks. Code blocks may be written by following the [Fenced code block](https://github.github.com/gfm/#fenced-code-blocks) syntax in the GFM spec. In addition, expressive-code adds support for the following features:

- [Frame titles](https://expressive-code.com/key-features/frames/)
- [Content highlighting](https://expressive-code.com/key-features/text-markers/)
- [Collapsible line ranges](https://expressive-code.com/plugins/collapsible-sections/)

Because most Markdown parsers don't accept additional frame decorations, the dev hub includes a special `<CodeBlock>` component that accepts the following props:

| Prop        | Data type | Required | Description                                                                                         |
| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `title`     | String    | No       | A title that is added to the top of the code block                                                  |
| `highlight` | String    | No       | A string of highlighted elements. Can be written as a string, a `{range}` object, or a regex string |
| `ins`       | String    | No       | Content that has been *added* in a diff                                                             |
| `del`       | String    | No       | Content that has been *removed* in a diff                                                           |
| `collapse`  | String    | No       | A range of lines to collapse                                                                        |

### Examples

To give the frame a title, add a `title` prop

````mdx
<CodeBlock title="build.gradle">

```groovy
dependencies {

}
```

</CodeBlock>

````

To highlight a single line, add a `{range: <line_number}` prop.

````mdx
<CodeBlock highlight="{range: 2}">

```java
AdjustConfig config = new AdjustConfig(this, appToken, environment);
config.setFbAppId(<FB_APP_ID_STRING>); // This line will be highlighted
Adjust.initSdk(config);
```

</CodeBlock>

````

To highlight multiple lines, pass a range to the `{range: <line_range>}` prop.

````mdx
<CodeBlock highlight="{range: 1-2}">

```java
AdjustConfig config = new AdjustConfig(this, appToken, environment); // This line will be highlighted
config.setFbAppId(<FB_APP_ID_STRING>); // This line will be highlighted
Adjust.initSdk(config);
```

</CodeBlock>

````

To highlight a word or multiple words, pass the words as a list.

````mdx

<CodeBlock highlight="me, dogs">

```text
Highlight me but not them
Highlight dogs but not cats
```

</CodeBlock>

````

To escape double quotes (to highlight a string containing quotes), pass the prop as a JSON object and escape the quotes with a slash (`\"`).

````mdx

<CodeBlock highlight={"\"me\", \"dogs\""}>

```text
Highlight "me" but not "them"
Highlight "dogs" but not "cats"
```

</CodeBlock>

````

### Syntax highlighting

Expressive code supports syntax highlighting through [shiki](https://shiki.matsu.io/). All languages that are supported in Textmate should be supported. Always enter the language of the code block to enable highlighting. If the language isn't known, or isn't a programming language (e.g. log outputs), use `text` as the language.

````markdown
```objective-c
[Adjust setEnabled:YES];
```
````

## Callouts

Callouts are components which display additional information in visually distinct ways. Callouts implement the ATLAS [Banner component](https://atlas.adeven.com/docs/components/Banner).

| Prop    | Data type | Required                   | Description                                                                          |
| ------- | --------- | -------------------------- | ------------------------------------------------------------------------------------ |
| `type`  | String    | No. Defaults to `info`     | Available values: `info` \| `note` \| `tip` \| `warning` \| `important` \| `seealso` |
| `title` | String    | No. Defaults to the `type` | An optional title. Overrides the title inferred from the `type`                      |

Callouts infer a title from the `type` by default. You can override this by passing a title to the `title` prop.

```mdx
<Callout title="Default callout with custom label">

This is a default callout. It **renders** [Markdown](https://markdownguide.org/).

</Callout>
```

### Callout types

Follow these rules when using callouts:

- A `note` callout is used to highlight additional information to the user.
- A `tip` callout highlights suggestions or tips that are **recommended** but **not required**.
- A `warning` callout contains information that highlights negative consequences.
- An `important` callout contains information that the user **shouldn't ignore**.
- A `seealso` callout contains links to additional or supplemental documentation or context.

##  Accordions

Accordions are components which visually hide additional information to make a page less busy. Accordions implement the ATLAS [Accordion component](https://atlas.adeven.com/docs/components/Accordion).

| Prop    | Data type | Required | Description                                                            |
| ------- | --------- | -------- | ---------------------------------------------------------------------- |
| `title` | String    | Yes      | The title of the accordion                                             |
| `badge` | String    | No       | An optional label that appears on a badge at the side of the accordion |

> **Note**: Only **additional** information – such as examples – should be placed in dropdowns. Any required information must not be hidden.

```mdx
<Accordion title="Example accordion">

This is an Accordion element. It **contains** [Markdown](https://www.markdownguide.org/).

</Accordion>
```

You may optionally add a [badge](https://atlas.adeven.com/docs/components/Accordion#badge) to an accordion component to add information such as target platform.

```mdx
<Accordion title="Example accordion" badge="iOS">

This is an Accordion element. It **contains** [Markdown](https://www.markdownguide.org/).

</Accordion>
```

## Content versions

The information in this repository targets multiple SDK versions. Both **major** and **minor** versions can be notated using MDX components.

### SDK versions

The `SdkVersion` component enables the author to mark content as applicable **only** to specific **major** versions of an SDK. Adding a `SdkVersion` component to a page automatically adds a version selector to the top of the page. When the reader switches to a different version, only content contained within a `SdkVersion` block with a matching `version` is rendered.

SDK versions **persist** across pages. The selected value is stored in the user's browser cache and will apply to any page that has matching `SdkVersion` content.

> **Note**: any content **not** wrapped in a `<SdkVersion>` block is rendered regardless of which version is selected.

| Prop      | Data type | Required | Description                                              |
| --------- | --------- | -------- | -------------------------------------------------------- |
| `version` | String    | Yes      | The major version number the enclosed content applies to |

```mdx
<SdkVersion version="v5">

Content in Markdown for v5.

</SdkVersion>

<SdkVersion version="v4">

Content in Markdown for v4.

</SdkVersion>
```

### API versions

The `ApiVersion` component enables the author to mark content as applicable **only** to specific **major** versions of an API. Adding a `ApiVersion` component to a page automatically adds a version selector to the top of the page. When the reader switches to a different version, only content contained within a `ApiVersion` block with a matching `version` is rendered.

API versions ** do not persist** across pages. This is because APIs are not updated at the same time.

> **Note**: any content **not** wrapped in a `<ApiVersion>` block is rendered regardless of which version is selected.

| Prop      | Data type | Required | Description                                              |
| --------- | --------- | -------- | -------------------------------------------------------- |
| `version` | String    | Yes      | The major version number the enclosed content applies to |

```mdx
<ApiVersion version="v1">

Content in Markdown for v1.

</ApiVersion>

<ApiVersion version="v2">

Content in Markdown for v2.

</ApiVersion>
```

### Minor versions

The `MinorVersion` component enables the author to indicate when an SDK feature was `added`, `changed`, or `removed`.

| Prop      | Data type | Required | Description                                     |
| --------- | --------- | -------- | ----------------------------------------------- |
| `added`   | string    | No       | The version in which the feature was added.     |
| `changed` | string    | No       | The version in which the feature was changed.   |
| `removed` | string    | No       | The version in which the feature was deprecated |

```mdx
<MinorVersion added="v4.24.0">

The `trackEvent` feature enables you to send event information from your mobile app to Adjust's servers.

</MinorVersion>
```

## Tabbed content

Tabs are used to group information together and enable readers to switch between the content they want to see. Tabs may be **synchronized** to allow all tabs groups to update when the reader selects a tab with a corresponding `sync` ID.

| Prop    | Data type | Required | Description                                                                                                                                             |
| ------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | String    | Yes      | The title of the tab                                                                                                                                    |
| `icon`  | IconName  | No       | An optional icon that appears on the left of the panel. See [the list of icons in ATLAS](https://atlas.adeven.com/docs/components/Icon#available-icons) |
| `sync`  | String    | No       | The sync ID of the tab. Add the same `sync` ID to all tabs you want to synchronize.                                                                     |

```mdx
<Tabs>
<Tab title="Tab 1" sync="tab1">

This is tab information in tab 1

</Tab>
<Tab title="Tab 2" sync="tab2">

This is tab information in tab 2

</Tab>
</Tabs>
```

## Tables

Tables are used to group information together in a readable way. All tables in Adjust's documentation render to [Atlas TableV2 components](https://atlas.adeven.com/docs/components/TableV2).

Use [GFM table syntax](https://github.github.com/gfm/#tables-extension-) to write tables in a way that is readable in plain text. Use the following props to control how the resulting table is displayed.

| Prop        | Data type | Required | Description                                                                                                       |
| ----------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `height`    | Number    | No       | The height (in pixels) that the table should take up. Leave this empty to take up the full height of the content. |
| `search`    | Boolean   | No       | Whether to include a search input. Defaults to `false`.                                                           |
| `resizable` | String    | No       | A list of columns that should be resizable                                                                        |
| `width`     | String    | No       | A list of columns and their width, written as `column_number: width_in_pixels`                                    |
| `autoWidth` | String    | No       | A list of columns that should be automatically sized                                                              |
| `noborder`  | Boolean   | No       | Whether to remove the table's borders. Borders are added by default.                                              |
| `noflex`    | Boolean   | No       | Whether to prevent the table from taking up the full width of its parent element (default).                       |
| `striped`   | Boolean   | No       | Whether the table should be highlighted by alternating rows.                                                      |

```mdx
<Table noborder autoWidth="1" width="2: 150" resizable="3" search>

| Column 1  | Column 2                  | Column 3                   |
| --------- | ------------------------- | -------------------------- |
| Apple     | Apples are nice fruit     | You should search for them |
| Pear      | Pears are nice fruit      | You should search for them |
| Grape     | Grapes are nice fruit     | You should search for them |
| Banana    | Bananas are nice fruit    | You should search for them |
| Pineapple | Pineapples are nice fruit | You should search for them |

</Table>
```