Documentation guide

This is a work in progress.

Style guide

Follow the Google Developer Documentation Style Guide.

Variables

You can use the following variables in the Dart documentation.

Variable	Result
{{site.dart_api}}	https://api.dartlang.org
{{site.data.pkg-vers.SDK.channel}}	stable or dev

Semantic line breaks

See Semantic line breaks (<=80 chars).

Images

The default way to add an image is to use an image tag. For example:

![Project configurations](/assets/images/docs/development/platform-integration/app-extensions/configs.png)

For additional ways to serve images, see Images

Links

See URLs

Anchors

If you need to add an anchor to a page, but not attach it to a heading use this format:

<a id="control-flow-operators" aria-hidden="true"></a>

Markdown and HTML

See Markdown and HTML

Page metadata

---
title: Dart SDK Archive
description: Download a specific version of the Dart SDK.
---

There are more fields that you can add. For details, see Top matter (YAML)

Notes

:::note
Note text goes here.
:::

See Asides (notes, tips, warnings, ...)

Tips

:::tip
Tip text goes here.
:::

See Asides (notes, tips, warnings, ...)

Warnings

:::warning
Warning text goes here.
:::

See Asides (notes, tips, warnings, ...)

Tabs

{% tabs "device-type-tabs" %}

{% tab "Android" %}

Android content here.

{% endtab %}

{% tab "iOS" %}

iOS content here.

{% endtab %}

{% endtabs %}

Code samples

Most code samples in the docs need to be generated from code excerpts. If you see a tag that looks like the following in the docs, the code sample is being generated from a code excerpt.

<?code-excerpt "examples/main.dart (optional-region-name)" arg0="value0" ...?>
```dart
void main() {}
```

Don't attempt to change the code sample directly in the markdown file. If you do, your PR will fail when you try and post it for review. To learn more about code excerpts see the Code excerpts README.

Display file name above code sample

```kotlin title="MainActivity.kt"
put code here
```

Display results

Code results should be styled with the plaintext keyword.

```plaintext
i = 1, j = 1
i = 1, j = 2
i = 1, j = 3
i = 2, j = 1
i = 2, j = 2
outerLoop exited
```

Show that sample produces error

```dart tag=fails-sa
// put failing code here
```

Suppress analysis warnings

If you are using code excerpts to generate code samples and you want to suppress an intended error or warning, you can add a comment in your code excerpt for this. To learn more, see https://dart.dev/tools/analysis

Update Dart version for excerpts

Look at this PR: https://github.com/dart-lang/site-www/pull/6576

Test against beta branch

To run tests against the beta branch of Dart, use the following command to switch to the beta branch:

flutter channel beta && flutter upgrade

Test against stable branch

To run tests against the stable branch of Dart, use the following command to switch to the stable branch:

flutter channel stable && flutter upgrade

Generated content

Some parts of the documentation are created in source files elsewhere and need to be generated for the Dart documentation.

Lints

Update the linter rules here: https://dart.dev/tools/linter-rules

./dash_site generate-lints

Diagnostics

Update diagnostic messages here: https://dart.dev/tools/diagnostics

./dash_site generate-diagnostics

Terms and definitions

Terms and definitions should follow this formatting style:

Term a
: Definition a.

Term b
: Definition b.

Example: https://dart.dev/tools/dart-compile#prod-compile-options