Skip to content

Markdown primer

Jump to bottom
Ciarán Ainsworth edited this page Feb 26, 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 underscores (__) instead of asterisks (**) 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:

Where sensible, assign titles that clearly show which file the code should be written in, or which clearly explain what type

Note: Frame titles aren't translated. Don't put essential information in the frame title.

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.

Major versions

The Version component enables the author to mark content as applicable only to specific major versions of an SDK or API. Adding a Version 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 Version block with a matching version is rendered.

Note: any content not wrapped in a <Version> 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 
<Version version="v5">

Content in Markdown for v5.

</Version>

<Version version="v4">

Content in Markdown for v4.

</Version>

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 Boolean No Whether readers should be able to resize columns. If not set, columns are sized automatically.
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 resizable 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