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.
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:
We truly thank you for your willingness and helpfulness in keeping the website docs up to date!
For changes beyond simple text and CSS tweaks, we recommend building the site.
Install the following tools, if you don't have them already:
bash
,
and setup might not work if you use another shell.choco install make
.
Other options include using a
subsystem.npm install -g firebase-tools
.
For full setup details, read the
Firebase CLI documentation.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 are working in the Windows desktop environment,
make sure you have Git autocrlf
set to input
before initializing the submodules.
This ensures that line endings are handled correctly
before any Bash scripts are executed within the submodules.
See issue 6201 for details.
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-submodules
option:
$ 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 submodule
command to refresh submodules:$ git pull; git submodule update --init --recursive
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 _site
directory 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 watched
messages. 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 vim
directly in a shell in the container.
To start a container shell, run docker-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
.
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.
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.
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
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 bash
shell, change to the repo directory
and initialize Firebase:
$ npx firebase init
If you created a new project, add it using the
firebase use
command:
$ 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 and deploy to the specified staging site:
$ make stage-local
Your personal version of the Flutter website is now deployed to Firebase. Copy the serving URL from the command output.
Warning
Before staging the site on Firebase, terminate all instances serving the site locally withmake up
.
A build that fails with the error
=> ERROR: some code excerpts were not refreshed!
means that one or more code excerpts in the markdown file
aren't identical to the
code in the corresponding .dart
file.
To resolve this error,
from the root of the website
directory,
run ./tool/refresh-code-excerpts.sh
.
For more information see Code excerpts .
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:
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。