• Stars
    star
    2,573
  • Rank 17,325 (Top 0.4 %)
  • Language
    Dart
  • License
    Other
  • Created almost 9 years ago
  • Updated 7 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Flutter documentation web site

Flutter logo

Flutter website

Build Status OpenSSF Scorecard

Table of contents

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.", avoid writing in first person, and avoid writing in future tense. 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 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

Setting up your local environment and serving changes

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

    $ git checkout -b <BRANCH_NAME>
  2. 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.

  3. Run the initial setup command:

    $ make setup
  4. 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.

  5. View your changes in the browser by navigating to http://localhost:4002.

    Note: Unless you're editing files under site-shared, you can safely ignore ERROR: directory is already being watched messages. For details, see #1363.

  6. 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)
  7. Commit your changes to the branch and submit your PR.

  8. 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 run make 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:

https://gist.github.com/d7b09149ffee2f0535bb0c04d96987f5

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.

  1. If you don't already have a Firebase project, navigate to the Firebase Console and create your own Firebase project (for example, my-foo).

  2. In a separate bash shell, change to the repo directory and initialize Firebase:

    $ npx firebase init
  3. 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
  4. Tell Firebase that you want to deploy to your project:

    $ npx firebase use my-foo
    Now using alias staging (my-foo)
  5. 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 with make up.

Refreshing code excerpts

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 .

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:

More Repositories

1

flutter

Flutter makes it easy and fast to build beautiful apps for mobile and beyond
Dart
157,868
star
2

plugins

Plugins for Flutter maintained by the Flutter team
Dart
17,165
star
3

samples

A collection of Flutter examples and demos
Dart
15,939
star
4

engine

The Flutter engine
C++
6,852
star
5

gallery

Flutter Gallery is a resource to help developers evaluate and use Flutter
Dart
5,866
star
6

packages

A collection of useful packages maintained by the Flutter team
Dart
3,600
star
7

pinball

Google I/O 2022 Pinball game built with Flutter and Firebase
Dart
2,097
star
8

flutter-intellij

Flutter Plugin for IntelliJ
Java
1,906
star
9

codelabs

Flutter codelab examples
C
1,568
star
10

devtools

Performance tools for Flutter
Dart
1,466
star
11

news_toolkit

A news template application built in Flutter, by Google and Very Good Ventures. Learn more at: https://flutter.github.io/news_toolkit
Dart
1,016
star
12

photobooth

Google I/O 2021 Photo Booth built with Flutter and Firebase
Dart
894
star
13

io_flip

Google I/O 2023 FLIP AI-designed card game built with Flutter & Firebase
Dart
597
star
14

flutter_clock

Dart
542
star
15

put-flutter-to-work

A Flutter add-to-app demo you can try with your own apps
Dart
309
star
16

holobooth

Jump into a new reality to bring Dash and Sparky to life!
Dart
230
star
17

tests

Contributed tests for Flutter
Dart
219
star
18

uxr

UXR work for Flutter
Dart
214
star
19

cocoon

Flutter's build coordinator and aggregator
Dart
182
star
20

impeller

Affects Flow
155
star
21

buildroot

Build environment for the Flutter engine
Python
120
star
22

assets-for-api-docs

Static assets for embedding into docs.flutter.io
Dart
113
star
23

tools_metadata

Metadata files about the flutter framework
Dart
66
star
24

web_installers

Web install scripts for CI for Flutter Web
Dart
42
star
25

goldens

Shell
41
star
26

platform_tests

Tools & tests to verify Flutter's fidelity on specific platforms
Dart
37
star
27

games

Home of the Flutter Casual Games Toolkit and other Flutter gaming templates
Dart
27
star
28

.github

Default community health files for Flutter
26
star
29

flutter-github-scripts.dart

Scripts to facilitate generating reports on the health of the Flutter repositories.
Dart
19
star
30

flutter.github.io

Root of flutter.github.io
HTML
13
star