Flutter documentation website
The documentation site for the Flutter framework,
built with Jaspr and hosted on Firebase.
Issues, bugs, and requests
We welcome contributions and feedback on our website.
Please file a request in our
issue tracker
or create a pull request.
For simple changes (such as tweaking some text),
it's easiest to make changes using the GitHub UI.
If you have an issue with the
API docs on api.flutter.dev,
please file them on
the flutter/flutter repo,
not on this (flutter/website) repo.
The API docs are embedded in Flutter's source code,
so the engineering team handles them.
Before you submit a PR
We love it when the community gets involved in improving our docs!
Here are a few things to keep in mind before you submit a PR:
- When triaging issues,
we sometimes label an issue with the tag PRs welcome.
However, we welcome PRs on other issues as well—
it doesn't have to be tagged with that label.
- Please don't run our docs through Grammarly (or a similar tool)
and submit those changes as a PR.
- We follow the Google Developer Documentation Style Guidelines—
for example, avoid "i.e." or "e.g.",
avoid writing in the first person,
and avoid the future tense.
You can start with the
style guide highlights
or the word list,
or use the search bar at the top of every style guide page.
We truly thank you for your willingness and helpfulness
in keeping the website docs up to date!
Contributing
To update this site, fork the repo, make your changes,
and generate a pull request.
For small, contained changes (such as style and typo fixes),
you probably don't need to build this site.
Often you can make changes using the GitHub UI.
If needed, we can stage the changes automatically in your pull request.
If your change involves code samples, adds/removes pages, or affects navigation,
please build and test your work before submitting.
If you want or need to build the site, follow the steps below.
Build the site
For changes beyond simple text and CSS tweaks,
we recommend running the site locally to
enable an edit-refresh cycle.
Get the prerequisites
To build and develop the site, you'll need to
install the latest stable release of Flutter, which includes Dart.
If you don't have Flutter or need to update, follow the
instructions at Install Flutter or Upgrading Flutter.
If you already have Flutter installed, verify it's in your path
and is the latest stable version:
flutter --version
Clone this repo
If you're not a member of the Flutter organization,
we recommend you create a fork of this repo under your own GitHub account
and then submit a pull request from that fork.
Once you have a fork (or you're a Flutter org member),
clone the repository with git clone:
git clone https://github.com/flutter/website.git
Set up your local environment and serve changes
Before you continue setting up the site infrastructure,
verify that the correct version of Flutter is set up and available by
following the instructions in Get the prerequisites.
-
Optional: After cloning the repo,
create a branch for your changes:
git checkout -b <BRANCH_NAME>
-
From the root directory of the repository,
fetch the site's Dart dependencies.
dart pub get
-
From the root directory, run the dash_site tool to
validate your setup and learn about the available commands.
dart run dash_site --help
-
From the root directory, serve the site locally.
dart run dash_site serve
This command generates and serves the site on a
local port that's printed to your terminal.
-
View your changes in the browser by navigating to
the local URL printed to your terminal.
-
Make your changes to the local repo.
To view your changes in the browser,
you'll need to refresh the page.
The site should automatically rebuild on most changes, but if
something doesn't update, exit the process and rerun the command.
-
Commit your changes to the branch and submit your PR.
If your change is large, or you'd like to test it,
consider validating your changes.
[!TIP]
To find additional commands that you can run,
run dart run dash_site --help from the repository's root directory.
Validate your changes
Check documentation and example code
If you've made changes to the code in
the /examples, /sites, or /tool directories,
commit your work, and then run the following command to
verify that it is up to date and matches site standards.
dart run dash_site check-all
If this script reports any errors or warnings,
address them and rerun the command.
If you have questions, leave a comment on your issue or pull request,
and we'll do our best to help.
You can also chat with us on the #hackers-devrel channel
on the Flutter contributors Discord!
Check links
If you've made changes to the content and want to check that all
internal links and Markdown link references are valid,
build the site locally and run the following commands.
-
Build the site locally.
dart run dash_site build
-
Verify all Markdown link references are resolved.
dart run dash_site check-link-references
-
Verify that all internal links are valid.
[!NOTE]
This command relies on the firebase CLI tool being on your PATH.
If you haven't installed it or updated it in a while,
follow Set up or update the Firebase CLI.
dart run dash_site check-links
If either command reports any errors or warnings,
address them, rebuild the site, and rerun the command.
Refresh code excerpts
A build that fails with the error
Error: Some code excerpts need to be updated!
means that one or more code excerpts in the site Markdown files
aren't identical to the code regions declared
in the corresponding .dart files.
The .dart files are the source of truth for code snippets,
and the preceding <?code-excerpt> instructions in Markdown files specify
how the snippets are copied from the .dart files.
To resolve this error and update the Markdown snippets to match,
from the root of the website directory,
run dart run dash_site refresh-excerpts.
To learn more about creating, editing, and using code excerpts,
check out the excerpt updater package documentation.
