Skip to content

Documentation guide

Jump to bottom
Connie Ooi edited this page Sep 24, 2025 · 57 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 include dynamic code samples in your documentation:

  1. Create a source file (or use an existing one) for your code sample.
  2. Define the excerpt region. For detailed instructions, see Defining excerpt regions.
  3. Use injection instructions to inject the code sample from a source file into your desired Markdown file. See Inject instructions.
  4. Immediately after the injection instructions, you must denote an empty Markdown code block with the language of the code sample.
```dart

```
  1. Run the refresh-excerpts command in your terminal.
dart run dash_site refresh-excerpts

You must run this same command any time you make updates to your source code sample to ensure your documentation remains current.

Display file name above code sample

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

Highlight code lines

To highlight specific lines in a code sample:

  1. On the same line as the opening backticks for the code block, insert the argument highlightLines=.
  2. Count the line numbers within the code block itself, not based on the surrounding file.
  3. List the line numbers you want to highlight, separated by commas. Use a hyphen (-) to indicate a line range. Do not include spaces between commas or hyphens.
```yaml highlightLines=1,4-5
dependencies:
  kittens:
    git:
      url: [email protected]: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.

Diagnostic messages

A technical writer should review diagnostic messages that go into the Dart or Dart package codebase. Messages are usually stored in messages.yaml files.

Changelogs

A technical writer should review changelogs as needed. The changelog is usually the CHANGELOG.md file and should follow the Google Developer Documentation Style Guide.

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