Skip to content

Markdown primer

Jump to bottom
Ciarán Ainsworth edited this page Jun 3, 2024 · 8 revisions

Adjust's SDK documentation is written using GitHub-flavored markdown (GFM) enhanced with MDX 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

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 to render code blocks. Code blocks may be written by following the Fenced code block syntax in the GFM spec. In addition, expressive-code adds support for the following features:

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

<CodeBlock title="build.gradle">

```groovy
dependencies {

}
```

</CodeBlock>

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

<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.

<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.

<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 (\").

<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. 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.

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

Callouts

Callouts are components which display additional information in visually distinct ways. Callouts implement the ATLAS Banner component.

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.

<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.

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.

<Accordion title="Example accordion">

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

</Accordion>

You may optionally add a badge to an accordion component to add information such as target platform.

<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 
<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 
<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 
<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
sync String No The sync ID of the tab. Add the same sync ID to all tabs you want to synchronize. 
<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.

Use GFM table syntax 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. 
<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>

Repo information

Guides

Clone this wiki locally