Flutter website
Note: We've made significant changes to this repo to make it easier to use and maintain. If you've already cloned this repo, please do it again. The most significant differences include:
- If you want to build the site, a Docker container now makes build setup simpler. For example, you no longer need to install nvm.
- The default branch is now called
main(it was previouslymaster).- Some files — in particular, image files — have been moved.
Stay tuned for another significant update to the website repo later this year.
Thanks, as always, for your continued support!
Table of contents
- Issues, bugs, and requests
- Before you submit a PR
- Before you build this site
- Setting up your local environment and serving changes
- Creating and/or editing DartPad example code
- Deploying to a staging site
- Writing for flutter.dev
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 those issues 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 those.
Before you submit a PR
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 tag PRs 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 the Google Developer Documentation Style Guidelines — for example, don't use "i.e." or "e.g.", and avoid writing in first person. You can start with the style guide highlights or the word list, or use the search bar that's 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!
Before you build this site
For changes beyond simple text and CSS tweaks, we recommend building the site.
1. Get the prerequisites
Install the following tools, if you don't have them already:
- bash, the Bourne shell. These instructions assume you're using
bash, and setup might not work if you use another shell. - GNU Make. On Windows the easiest way to install Make is
choco install make. Other options include using a subsystem. - Docker. We use Docker for local dev, tests, and building the site. Install it from https://docs.docker.com/get-docker/.
- Firebase CLI, for hosting the site locally. One way to get this is to run
npm install -g firebase-tools. For full setup details, read the Firebase CLI documentation.
2. Clone this repo and its submodules
Note: This repo has git submodules, which affects how you clone it. The GitHub documentation has general help on forking and cloning repos.
If you're outside of the Flutter organization, we recommend you create a fork of the 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:
-
Clone the repo and its submodule at the same using the
--recurse-submodulesoption:$ git clone --recurse-submodules https://github.com/<username-or-flutter>/website.git
OR
-
If you've already cloned the repo without its submodule, then run this command from the repo root:
$ git submodule update --init --recursive
Note: At any time during development you can use the
git submodulecommand to refresh submodules:$ git pull; git submodule update --init --recursive
Setting up your local environment and serving changes
-
Optional: After cloning the repo and its submodules, create a branch for your changes:
$ git checkout -b <BRANCH_NAME>
-
If the Docker Desktop application isn't already running, start it. Look at its status icon: if it has an exclamation point (
!), then update Docker Desktop. -
Run the initial setup command:
$ make setup
-
Serve the site locally (via
docker-compose):$ make up
The site is generated, and then the development server runs in the Docker container, with the generated
_sitedirectory visible locally. -
View your changes in the browser by navigating to
http://localhost:4002.Note: Unless you're editing files under
site-shared, you can safely ignoreERROR: directory is already being watchedmessages. For details, see #1363. -
Make your changes. The files are updated, and your browser view should update to reflect the changes. You can either edit files locally or use an editor like
vimdirectly in a shell in the container. To start a container shell, rundocker-compose exec site bash.Tip: If you aren't seeing the changes you expect, restart the server and rebuild the site from scratch:
$ make down && make clean && make up
In some rare cases you might want to force all running containers down:
$ docker rm -f $(docker ps -aq) -
Commit your changes to the branch and submit your PR.
-
When you've finished developing, shut down the Docker container:
$ make down
Tip: To find additional commands, read the
Makefile. For example, if you need to debug the Docker infrastructure, you can runmake debug.
Creating and/or editing DartPad example code
Most of the code used to create DartPad examples is hosted on GitHub. However, this repo also contains some *.dart files responsible for DartPad example code.
DartPad example code in GitHub gists
A typical DartPad example takes the form of an iframe, for example, within a codelab's Markdown file:
<iframe
src="{{ site.custom.dartpad.embed-flutter-prefix }}?id=d7b09149ffee2f0535bb0c04d96987f5"
style="border:1px solid lightgrey;margin-top:10px;margin-bottom:25px"
frameborder="no" height="500" width="100%">
iframe>
This iframe depends on the following GitHub gist URL:
For detailed instructions on how to use this approach to DartPad examples, see the DartPad embedding guide.
DartPad example code in this repo
Some DartPad example code remains in this repo:
src/_packages/dartpad_picker/web/dartpad_picker_main.dart
This code must be manually compiled, which also regenerates the associated JavaScript file in src/assets/js:
$ cd `src/_packages/dartpad_picker
$ ./compile.sh
Deploying to a staging site
You can deploy your local edits to a personal staging site as follows.
-
If you don't already have a Firebase project, navigate to the Firebase Console and create your own Firebase project (for example,
my-foo). -
In a separate
bashshell, change to the repo directory and initialize Firebase:$ npx firebase init
-
If you created a new project, add it using the
firebase usecommand:$ npx firebase use --add ? Which project do you want to add? <select the project you created> ? What alias do you want to use for this project? (e.g. staging) my-foo
-
Tell Firebase that you want to deploy to your project:
$ npx firebase use my-foo Now using alias staging (my-foo) -
Build the site via Docker with:
$ DISABLE_TESTS=1 make build
The
_sitedirectory refreshes locally. -
Deploy to the staging site:
$ make deploy
Your personal version of the Flutter website is now deployed to Firebase. Copy the serving URL from the command output.
Writing for flutter.dev
The site-shared repo contains infrastructure shared by most of our Dart and Flutter websites. Some of this README is in the doc directory in the site-shared repo.
For more information on using and writing for this repo, refer to the following docs:
Also check out the site-shared wiki:
![[PAGE ISSUE]: 'Creating flavors for Flutter'](https://avatars.githubusercontent.com/u/100226351?v=4)
![[PAGE ISSUE]: 'Cupertino (iOS-style) widgets'](https://avatars.githubusercontent.com/u/100537065?v=4)
0 Jan 4, 2022
20 Oct 26, 2022
2 May 30, 2022
7 Nov 2, 2022
20 Oct 11, 2022
30 Nov 11, 2022
428 Dec 30, 2022
70 Dec 13, 2022
362 Dec 29, 2022
3 Jan 27, 2022
1 Apr 27, 2022
46 Dec 29, 2022
171 Jan 4, 2023
54 Dec 31, 2022
15 Nov 1, 2022
11 Oct 10, 2022
46 Dec 27, 2022
3 Sep 6, 2021
7 Dec 17, 2022