Repository files navigation

We welcome contributions and feedback on our website!Please file a request in ourissue trackerand we'll take a look.

For simple changes (such as to CSS and text), you probably don't need to build this site.Often you can make changes using the GitHub UI.

If you want/need to build, read on.

Install the following tools if you don't have them already.

• bash, the Bourne shell. These instructions assume you're usingbash -- setup might not work using other shells.
• nvm, the Node Version Manager.
• rvm, the Ruby Version Manager.
• Flutter
• Dart SDK

IMPORTANT: Follow the installation instructions for each of the toolscarefully. In particular, configure your shell/environment sothat the tools are available in every terminal/command window you create.

NOTE: This repo has a gitsubmodule, which affects how you clone it.

Toclonethis repo, follow the instructions given in theGitHub help onCloning a repository, andchoose one of the followingsubmodule-cloning techniques:

• Clone this repo and its submoduleat the same, use the--recurse-submodules option:
  git clone --recurse-submodules https://github.com/flutter/website.git
• If you've already cloned this repo without its submodule, then runthis command from the repo root:
  git submodule update --init --remote

IMPORTANT:Whenever you update your repo, update the submodule as well:
git pull; git submodule update --init --remote

NOTE: It is safe to (re-)run all of the commands and scripts given below evenif you already have the required packages installed.

Open a bash terminal/command window and execute the following commands:

1. cd<path-to-this-repo>   # change toroot of this repo
2. source ./tool/env-set.sh   #initialize environment variables; install/use required Node & Ruby version
3. ./tool/before-install.sh   #install core set of required tools
4. ./tool/install.sh   #install everything else needed to build this site

IMPORTANT:

• Any time you create anew terminal/command window to work onthis repo,repeat steps 1 and 2 above.
• If you upgrade Dart then rerun all of the steps above.

1. Create a branch.

2. Make your changes.

3. Test your changes by serving the site locally. Run eitherone of these commands:

   • ./tool/serve.sh

   or

   • bundle exec jekyll serve --incremental --watch --livereload --port 4002

     Note: Unless you're editing files undersite-shared, you can safelyignoreERROR: directory is already being watched messages.For details, see#1363.

4. Prior to submitting, validate site links:
   ./tool/shared/check-links.sh

TIP:Sometimes Jekyll gets confused and seems to be out-of-sync. (This mighthappen when you pull from master and lots of image files have moved.) To fix this,stop theserve.sh script, remove the generated site files by hand, and thenrestart theserve.sh script:

^C$ rm -Rf ./_site/* ./.jekyll*$ ./tool/serve.sh

You can deploy your local edits to a personal staging site as follows (steps 1 and 2 need to be done only once):

1. In theFirebase Console,create your own Firebase project (e.g. 'mit-flutter-staging')

2. Tell Firebase about that project with the firebaseuse 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

3. Tell Firebase that you want to deploy to staging:

   $npx firebase use my-fooNow using alias staging (<your project name>)

4. Tell Firebase to deploy:

   $./tool/shared/deploy.sh --local my-foo=== Deploying to '<your project name>'...i  deploying hostingi  hosting: preparing _site directory for upload...✔  hosting: 213 files uploaded successfullyi  starting release process (may take several minutes)...✔  Deploy complete!

Deploy to thedefault firebase project (hosting the official site) using thiscommand:

./tool/shared/deploy.sh --local --robots ok default

(Eventually, this section should be expanded to its own page.)

The easiest way to syntax highlight a block of code is to wrapit with triple backticks followed by the language.

Here's an example:

classExampleWidgetextendsStatelessWidget {@overrideWidgetbuild(BuildContext context) {returnContainer();  }}

Do you want to highlight (make the background yellow)code inside a code block? Do you want to strike-throughcode inside a code block? We got that!

For syntax highlighting, plus yellow highlightingand strike-through formatting, use theprettify tagwith additional custom inline markup.

If you want to highlight a specific bit of code, use the[[highlight]]highlight this text[[/highlight]] syntaxwith theprettify tag.

For example:

{% prettify dart %}void main() {  print([[highlight]]'Hello World'[[/highlight]]);}{% endprettify %}

If you want to strike-through a specific bit of code, use the[[strike]]highlight this text[[/strike]] syntaxwith theprettify tag.

For example:

{% prettify dart %}void main() {  print([[strike]]'Hello World'[[/strike]]);}{% endprettify %}

Theprettify plugin will also unindent your code.

If you want to see how this functionality was added to this site, refer tothis commit.

You can include a specific range of lines from a file:

{% include includelines filename=PATH start=INT count=INT %}

PATH must be inside of_include. If you are including source code,place that code into_include/code to follow our convention.

The code snippets in the markdown documentation are validated as part of thebuild process. Anything within a '```dart' code fence will be extracted intoits own file and checked for analysis issues. Some ways to tweak that:

• If a code snippet should not be analyzed, immediately proceed it witha<!-- skip --> comment
• To include code to be analyzed, but not displayed, add that in a commentimmediately proceeding the snippet (e.g.,<!-- someCodeHere(); -->)
• A snippet without any import statements will have an import('package:flutter/material.dart')automatically added to it
• We ignore special formatting tags like[[highlight]].

The sample catalog's markdown files are generated by runningsample_page.dart from the Flutter github repo. Starting from the root of the Flutter repo:

cd examples/catalogdart bin/sample_page.dart '<commit hashcode here>'cp examples/catalog/.generated/*.md <your website repo>/catalog/samples

The generated markdown files will contain cloud storage links for sample app screenshots. Screenshots for each sample app are automatically generated for each Flutter repo commit. Choose a recent commit hashcode and confirm that the screenshots look OK.

If new sample apps have been added, update_data/catalog/widget.json. The entry for each widget class that's featured in a sample app should contain"sample" line like:

"sample": "ListView_index",

Thesample_page.dart app will print a list of all of the"sample" properties that should appear in thewidget.json file.