Skip to content

Documentation guide

Jump to bottom
Amanda Fitch edited this page Oct 27, 2025 · 74 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.

Dart Variable Flutter Variable Result
{{site.dart_api}} https://api.dartlang.org
{{site.dart.api}} https://api.flutter.dev/
{{site.data.pkg-vers.SDK.channel}} stable or dev
{{site.repo.dart.sdk}} https://api.dart.dev
{{site.dart-api}} https://api.dart.dev
{{site.dart-site}} https:dart.dev
{{site.flutter-docs}} https://docs.flutter.dev
{{site.dartpad}} {{site.dartpad}} https://dartpad.dev/
{{site.pub-pkg}} {{site.pub-pkg}} https://pub.dev/packages
{{site.repo.dart.org}} none https://github.com/dart-lang/

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)

Asides and other notes

Asides (sometimes known as alerts or callouts) can be added by wrapping a block of content in an open and closing triple colon (:::). The opening colons must be followed with the type of aside.

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

Types of asides

The following aside types are supported:

ID Color Default title Icon
note Blue Note Info
important Purple Important Exclamation
warning Orange Warning Warning sign
tip Green Tip Lightbulb
recommend Green Recommended Lightning bolt
flutter-note Blue Flutter note Flutter logo
version-note Blue Version note Git-like merge logo
experimental Red Experimental Wrench and hammer
secondary Grey -- --

Custom aside title

A custom title can optionally be specified after the type of aside. For example, "What's the point?" in the following aside:

:::secondary What's the point? 
Note text goes here.
:::

Tabs

<Tabs key="dev-os" wrapped="true">

<Tab name="Windows">

Windows content here.

</Tab>
<Tab name="macOS">

macOS content here.

</Tab>
<Tab name="Linux">

Linux content here.

</Tab>
</Tabs>

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

Feature availability

While we encourage Dart developers to develop with the latest beta or stable releases of the SDK, not all developers are able to right away. To avoid confusion for them and LLMs, it's important to clarify the ability and status of features we document.

Released features

For new features or changes that are released to the beta or stable channel without a flag, consider adding a version note with the required version.

Language-versioned changes

For language or tooling features that are language versioned, cross-link to the language version docs and indicate the language version required for the new feature or change.

:::version-note
Using digit separators requires a [language version][] of at least 3.6.
:::

[language version]: /resources/language/evolution#language-versioning

Language versions notes can be removed once the previous language version is no longer supported by the latest stable SDK. So for now, language version notes from 2.13 or later are kept, as the latest SDK (as of 2025-10-12) still supports language versions of 2.12 or later.

SDK changes

For SDK and core library features or changes that aren't language versioned, clarify the Dart SDK version support was added in.

:::version-note
Support for `dart install` was introduced in Dart 3.10.
:::

When to remove these notes can vary more compared to language versioned notes. The safe choice is when the Dart SDK's major version is increased, for example from 3 to 4. Otherwise, we tend to wait at least 4 stable releases (usually 1 year) before removing the note, unless it's likely developers might still benefit from the note. For example, notes about Dart's old separate CLI tools (such as dartfmt versus dart format now) were kept for over 2 years as the old command was commonly used and found across the internet.

Experimental and preview features

To prevent confusing or misleading developers when reading about or trying an experimental feature, it's important to clarify the experimental nature of a feature.

If a feature is available on the beta channel and no longer under a flag, consider instead documenting it the same way as a released feature as we encourage usage of the beta channel. It also makes updates to the docs no longer required once the next stable release is made.

If a feature is still experimental, such as only available on the dev channel, behind a flag, or expected to change heavily, add a warning note with additional context before the content.

:::experimental
Support for build hooks is experimental and
can only be used on the `main` channel.
:::
:::experimental
Support for private, named initializing parameters is in **progress** and
can be tried on the `main` channel with
the `private-named-parameters` [experiment flag enabled][experiment].
:::

[experiment]: /tools/experiment-flags

As part of each release, each feature marked as experimental should be reviewed for accuracy, either being updated for the current state, transitioned to a released feature note, or being completely removed if the experiment has ended.

Stage your docs

Github

  • Writing team members: If you are member of the Flutter or Dart writing team, your documentation PR is staged automatically when you create or update the PR. If the retention period for the staged project expires and a preview is no longer available you can re-stage your project by adding a comment called /gcbrun to your PR.

  • Other contributors: Only writing team members can stage document PRs on GitHub. Contact a member of the writing team. A writing team member will add a comment called /gcbrun to your PR and this will stage your PR.

On your personal computer

To stage a documentation project on your personal computer, open a terminal and execute this command:

./dash_site serve

Then open a Chrome web browser and go to this URL: http://localhost:4000/

Redirects

If a page or section of a page has moved or been renamed, create a redirect.

For example, these need redirects:

# topic is moved
lang/if-elements.md => lang/collections/if-elements.md

# topic is renamed
lang/if-elements.md => lang/if-and-for-elements.md

# section in topic is renamed
lang/elements#for => lang/elements#if-and-for

To add a redirect, find the firebase.json in your project and add a new alphabetically ordered line in it that looks like this:

{ "source": "/platform-integration/linux/install-linux", "destination": "/platform-integration/linux/setup", "type": 301 },

Make sure to add this inside of redirects:

{
  "hosting": {
    ...
    "redirects": [
      ...
      { "source": "/platform-integration/linux/install-linux", "destination": "/platform-integration/linux/setup", "type": 301 },
    ]

Clone this wiki locally