Skip to content

Documentation guide

Jump to bottom
Parker Lougheed edited this page Sep 9, 2025 · 63 revisions

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
{{site.repo.dart.sdk}} https://api.dart.dev
{{site.dart-api}} https://api.dart.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>

Headings

Use a static link

Every time you change a heading, the link for that heading changes. This means that you need to go through all of the Dart docs and update the links to point to the renamed section and also add a redirect to the new link. To avoid this, you can add a static link to a heading that never changes:

## How to complete a long task {: #long-task }

Hide from TOC

To hide a heading from the TOC, use this format:

## My heading {: .no_toc}

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

Highlight a line in the code sample

```yaml highlightLines=5
dependencies:
  kittens:
    git:
      url: git@github.com:munificent/kittens.git
      tag_pattern: v{{version}} # Find version-tag prefixed by 'v'.
    version: ^2.0.1
```

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

dart run dash_site generate-lints

Diagnostics

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

dart run dash_site generate-diagnostics

macOS versions

The macOS versions listed on the Get the Dart SDK page are sourced from the macOS json file. To add a new macOS version or update an existing one, you must modify this file. When adding a new macOS version, create an entry on the top of the json list.

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

Clone this wiki locally