Repository files navigation

Thedocumentation site for theFlutter framework,built withEleventy and hosted onFirebase.

We welcome contributions and feedback on our website.Please file a request in ourissue trackeror create apull 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 theAPI docs onapi.flutter.dev,please file those issues ontheflutter/flutter repo,not on this (flutter/website) repo.The API docs are embedded in Flutter's source code,so the engineering team handles those.

We love it when the community gets involved in improving our docs!But here are a few notes to keep in mind before you submit a PR:

• When triaging issues,we sometimes label an issue with the tagPRs welcome.But 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 similar)and submit those changes as a PR.
• We follow theGoogle Developer Documentation Style Guidelines —for example, don't use "i.e." or "e.g.",avoid writing in first person,and avoid writing in future tense.You can start with thestyle guide highlightsor theword list,or use the search bar that's at the top of every style guide page.

We truly thank you for your willingness and helpfulnessin keeping the website docs up to date!

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,do consider building and test your work before submitting.

If you want or need to build the site, follow the steps below.

For changes beyond simple text and CSS tweaks,we recommend running the site locally toenable an edit-refresh cycle.

Install the following tools to build and develop the site:

The latest stable release of Flutter, which includes Dart,is required to build the site and run its tooling.If you don't have Flutter or need to update, follow theinstructions atInstall Flutter orUpgrading Flutter.

If you already have Flutter installed, verify it's on your pathand already the latest stable version:

flutter --version

Thelatest stable LTS release of Node.js is required to build the site.If you don't have Node.js or need to update, download yourcomputer's corresponding version and follow the instructionsfrom theNode.js download archive.If you prefer, you can use a version manager such asnvm,and runnvm install from the repository's root directory.

If you already have Node installed, verify it's available on your pathand already the latest stable version(currently22.12 or later):

node --version

If your version is out of date,follow the update instructions for how you originally installed it.

If you're not a member of the Flutter organization,we recommend youcreate a fork of this repo under your own account,and then submit a PR from that fork.

Once you have a fork (or you're a Flutter org member),choose one of the following submodule-cloning techniques:

1. Clone the repo and its submodule at the same timeusing the--recurse-submodules option:

   git clone --recurse-submodules https://github.com/flutter/website.git

2. If you've already cloned the repo without its submodule,then run this command from the root of the repository:

   git submodule update --init --recursive

git pull && git submodule update --init --recursive

Before you continue setting up the site infrastructure,verify the correct versions of Flutter and Node.js are set up and available byfollowing the instructions inGet the prerequisites.

1. Optional: After cloning the repo and its submodules,create a branch for your changes:

   git checkout -b <BRANCH_NAME>

2. From the root directory of the repository,fetch the site's Dart dependencies.

   dart pub get

3. Optional: We recommend you usepnpm, but you can also usenpm.Installpnpm, an alternative, efficient package manager fornpm packages. If you already havepnpm, verify you have thelatest stable version.

   node --version

   If you don't already havepnpm installed, we recommendusingcorepack to install and managepnpm versions,sincecorepack is bundled with most installations ofNode. If you installednode using Homebrew, you'll needto install corepack separately:

   brew install corepack

   If you haven't usedcorepack before, you'll need tofirst enable it withcorepack enable.Then, to install the correctpnpm version, from theroot directory of the repository, runcorepack install:

   corepack enable;corepack install

   To installpnpm without usingcorepack, youcan use your preferredinstallation method.

4. (optional) Once you havepnpm installed and setup,fetch the site's npm dependencies usingpnpm install.We highly recommend you usepnpm, but you can also usenpm.

   pnpm install

   Rerunpnpm install whenever you incorporate thelatest changes to themain branch or if youexperience dependency or import errors when building the site.

5. From the root directory, run thedash_site tool tovalidate your setup and learn about the available commands.

   ./dash_site --help

6. From the root directory, serve the site locally.

   ./dash_site serve

   This command generates and serves the site on alocal port that's printed to your terminal.

7. View your changes in the browser by navigating tohttp://localhost:4000.

   Note the port might be different if4000 is taken.

   If you want to check the raw, generated HTML output and structure,view the_site directory in a file explorer or an IDE.

8. Make your changes to the local repo.

   The site should automatically rebuild on most changes, but ifsomething doesn't update, exit the process and rerun the command.Improvements to this functionality are planned.Please open a new issue to track the issue if this occurs.

9. Commit your changes to the branch and submit your PR.

If your change is large, or you'd like to test it,considervalidating your changes.

If you've made changes to the code in the/examples or/tool directories,commit your work, then run the following command toverify it is up to date and matches the site standards.

./dash_site check-all

If this script reports any errors or warnings,then address those issues and rerun the command.If you have any issues, leave a comment on your issue or pull request,and we'll try our best to help you.You can also chat with us on the#hackers-devrel channelon theFlutter contributors Discord!

A build that fails with the errorError: Some code excerpts needed to be updated!means that one or more code excerpts in the site Markdown filesaren't identical to the code regions declaredin the corresponding.dart files.

The.dart files are the source of truth for code snippets,and the preceding<?code-excerpt> instructions in Markdown files specifyhow the snippets are copied from the.dart files.

To resolve this error and update the Markdown snippets to match,from the root of thewebsite directory,run./dash_site refresh-excerpts.

To learn more about creating, editing, and using code excerpts,check out theexcerpt updater package documentation.

Submitted pull requests can be automatically stagedby a site maintainer.If you'd like to stage the site yourself though,you can build a full version and upload it to Firebase.

1. If you don't already have a Firebase project,

• Navigate to theFirebase Consoleand create your own Firebase project (for example,flutter-dev-staging).

• Head back to your local terminal and verify that you are logged in.

  firebase login

• Ensure that your project exists and activate that project:

  firebase projects:listfirebase use <your-project>

2. From the root directory of the repository, build the site:

   ./dash_site build

   This builds the site and copies it to your local_site directory.If that directory previously existed, it will be replaced.

3. Deploy to your activated Firebase project's default hosting site:

   firebase deploy --only hosting

4. Navigate to your PR on GitHub and include the link of the staged version.Do consider adding a reference to the commit you staged,so that reviewers know if any further changes have been made.