# site-www is the Dart language website, and its code samples are checked in CI

> site-www holds the source of dart.dev, written in Dart and built with Jaspr, hosted on Firebase, and worked on through a dash_site command that serves the site locally and validates that every code excerpt in the Markdown still matches the Dart file it came from. It is the repository to fork when you want to fix a page on the Dart site, and the tooling is stricter than a typical docs site.

**dart-lang/site-www** — The source for the Dart website.

- Repository: https://github.com/dart-lang/site-www
- Website: https://dart.dev
- Stars: 1,056 · Forks: 794
- Language: Dart
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/dart-lang-site-www

## The site is a Dart program, not a folder of Markdown

site-www is the source for the Dart programming language site at dart.dev, and its primary language is Dart. That fact shapes everything about working on it. The repository is not a collection of Markdown files that get rendered by a generic static site generator. It is a Dart application, with a pubspec.yaml at the root, a src/ directory for the site content and code, a site/ directory, a tool/ directory holding the site tooling, and an examples/ directory containing runnable Dart projects that back the documentation. The site is built with Jaspr and hosted on Firebase, with firebase.json and a .firebaserc in the tree and a cloud_build/ directory for the deployment side. There is also a blog_redirects/ directory, which is the part of the repository that quietly keeps old URLs working, and an AUTHORS file. The audience is anyone who wants to correct or extend the Dart documentation, and the team is explicit that contributions of all kinds are welcome.

## Fork, clone, and serve with dash_site

The local setup is four commands once Dart is installed. The prerequisite is the latest stable release of Dart, which can be the Dart included in the Flutter SDK, and you check it with:

```bash
dart --version
```

If you are not a member of the Dart organization, the recommendation is to create a fork under your own account and submit a pull request from it, and the clone step is:

```bash
git clone https://github.com/dart-lang/site-www.git
```

From the root of the repository, you fetch dependencies, look at what the tool offers, and start the server:

```bash
dart pub get
dart run dash_site --help
dart run dash_site serve
```

The serve command generates the site and serves it on a local port that is printed to your terminal, and the README says to view it at http://localhost:8080, with the note that the port might be different if 8080 is taken. The site should rebuild automatically on most changes, and the documentation is honest that this is not perfect, since if something does not update you should exit the process and rerun the command, with improvements planned and an issue to file if it happens. A branch is optional but sensible, created with git checkout -b and a name of your choosing.

## check-all guards the examples and the documentation together

The verification step is where this repository is unusual. If you have changed code in the /examples or /tool directories, you commit your work and then run:

```bash
dart run dash_site check-all
```

That command verifies that the documentation and the example code are up to date and match the site standards, and any errors or warnings it reports are meant to be fixed and the command rerun. The examples directory is not incidental. It holds one directory per topic, including analysis, async_await, concurrency, create_libraries, extension_methods, fetch_data, futures, iterables, language, misc, non_promotion, type_system and util, each with its own pubspec.yaml, plus analysis_options.yaml files and base configurations for dart_test in both standard and browser flavours. That is a lot of real, compiled Dart code sitting next to the prose, and check-all is what keeps the two in agreement.

## refresh-excerpts pulls code back out of the Dart files

The mechanism behind check-all is the excerpt updater, and understanding it explains the whole design. A build that fails with the error Error: Some code excerpts needed to be updated! means that one or more code excerpts in the site Markdown files are not identical to the code regions declared in the corresponding .dart files. The fix is a single command from the root of the repository:

```bash
dart run dash_site refresh-excerpts
```

So the documentation does not hand-copy the samples. It references regions of the real example files, and the build checks that the rendered Markdown still matches the source. That is a stronger guarantee than a documentation site that pastes code into prose, where a snippet rots the first time the example is edited, and it explains why a change to an example file can fail the build of the site. The link the README gives for the details points to the excerpt updater package documentation in the flutter/website repository, which is where that tooling lives.

## The Dartpedia tutorial chapters are tested, not just rendered

There is a second, more specific check for the tutorial. If you have modified code blocks in the Dartpedia tutorial chapters, under src/content/learn/tutorial, the command to run is:

```bash
dart run dash_site check-tutorial-code
```

It extracts each chapter's progressive workspace snapshot and verifies that every chapter analyzes cleanly and passes tests. You can pass --chapter with a 1-based chapter number or a slug ID to validate one chapter, or --verbose for detailed output. This is the strongest guarantee in the repository, and it is a different kind of promise from the rest of the site. A tutorial that walks a reader through building something, with each chapter a snapshot of a workspace that is supposed to analyse and pass its tests, is checked the same way a project would be. The cost is that a tutorial change is a heavier pull request than a prose change, since a failing chapter snapshot blocks the build, and the README's advice to comment on the issue or pull request if you hit problems, or to ask in the hackers-devrel channel on the Flutter contributors Discord, is there because these failures are not always obvious.

## Most fixes never need a build at all

The contribution guidance is built around that asymmetry. For small, contained changes such as style and typo fixes, the documentation says you probably do not need to build the site, and that changes can often be made using the GitHub UI, with the changes staged automatically in the pull request. The project asks contributors to start by looking for an issue that catches their interest, or to create an issue with a proposed change, and to add a comment so everyone knows the work is being done. The README points to the Contributing guidelines in CONTRIBUTING.md for the details. The split is a sensible one. Prose changes are reviewed by reading, and blocking them on a Dart toolchain and a local server would raise the cost of every typo fix to the cost of a code change. Anything that touches code samples, adds or removes pages, or affects navigation is where the guidance says you should build and test your work before submitting, and where the excerpt and tutorial checks apply.

## An active repository with a licence you have to read

The maintenance picture is straightforward. The last push was on 2026-10-15, the default branch is main, and the repository has no GitHub releases, which is normal for a site whose artifacts are deployed rather than versioned. The build status badge points at the GitHub Actions workflow, and the OpenSSF Scorecard badge links to the scorecard results, and the tree carries AGENTS.md along with.agents/ and.gemini/ directories, which is a sign that the site work now assumes machine agents taking part in it. The licence is the one thing to check before you reuse anything. It is not a licence identifier GitHub can classify, so you have to open the LICENSE file to see the terms, and the project keeps AUTHORS alongside it. The repository also has an analysis_options.yaml, so the Dart code in the site and the tools is linted with the same rules a Dart developer would expect, and a.github/ directory for the workflows and issue templates that make the contribution process work.

## Conclusion

site-www is the right repository to change when something on the Dart documentation site is wrong, and the contribution path is unusually friendly for small fixes, since a typo can be fixed through the GitHub interface without ever running the build. The tooling earns its keep for larger changes, because check-all and refresh-excerpts keep the documentation and the example code from drifting apart, which is the failure mode that slowly destroys a language site. It is not a repository to fork as a template for your own documentation, since it is bound to Jaspr, to Firebase and to the Dart team's publishing setup. Before you start, install the latest stable Dart, run dart run dash_site --help to see what the tool offers, and read the issue tracker first, because the project asks contributors to check for an existing issue before opening a new one.

## FAQ

### How do I build and serve the dart.dev site locally?

Install the latest stable Dart, clone the repository, then run dart pub get and dart run dash_site serve from the root. The command generates and serves the site on a local port printed to your terminal, and the README points at http://localhost:8080, noting the port may differ if 8080 is taken.

### What does the error about code excerpts needed to be updated mean?

It means one or more code excerpts in the site Markdown files are not identical to the code regions declared in the corresponding .dart files. Run dart run dash_site refresh-excerpts from the root of the repository to regenerate them.

### Do I need to build the site for a typo fix?

No. The README says that for small, contained changes such as style and typo fixes you probably do not need to build the site, and that changes can often be made using the GitHub UI. If the change involves code samples, adds or removes pages, or affects navigation, you should build and test before submitting.

### How is the Dartpedia tutorial code verified?

Run dart run dash_site check-tutorial-code. It extracts each chapter's progressive workspace snapshot and verifies that every chapter analyzes cleanly and passes tests, and you can narrow it with --chapter and --verbose.

## Sources

- [dart-lang/site-www on GitHub](https://github.com/dart-lang/site-www)
- [Issues](https://github.com/dart-lang/site-www/issues)
- [Project website](https://dart.dev)
- [README](https://github.com/dart-lang/site-www/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dart-lang-site-www