Skip to content

guidezpl/website

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Flutter logo

Flutter website

Build Status

NOTE: We have made significant changes to the flutter/website repo to make it easier to use and maintain, and the instructions in this file are changing. If you have already cloned it, please clone it again. The most significant differences include:

  • The website now uses a Docker container, so you need to install Docker, if you haven't already. This means that much of the tooling previously required (like nvm) is no longer required.
  • The default branch is renamed to main (it was previously master).
  • Files (and most specifically 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

We welcome contributions and feedback on our website. Please file a request in our issue tracker and we'll take a look.

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.

NOTE - 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.

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 realize that we follow (or try to follow) the Google Developer Documentation Style Guidelines. So please don't run our docs through Grammarly (or similar) and submit those changes as a PR. This guide is a reference doc and not meant to be read like a novel, but check out the highlights page or use the search bar to find your subject of interest. Also, the wordlist is very useful. (For example, don't use "i.e." or "e.g.", and avoid writing in first person.)

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

Before you build this 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 is used for local dev, tests and building the site. It can be installed from here.
  • Lastly, install the Firebase CLI for local deployment by running npm install -g firebase-tools. Read the docs for full setup.

2. Clone this repo and its submodules

NOTE - This repo has git submodules, which affects how you clone it.

To clone flutter/website (this repo), follow the instructions given in the GitHub help on Cloning a repository, then choose one of the following submodule-cloning techniques:

  • If you are 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.

  • Clone the repo and its submodule at the same using the --recurse-submodules option:

    $ git clone --recurse-submodules https://github.com/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

Set up your local environment and serve changes

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

    $ checkout -b <BRANCH_NAME>
  2. Then run the initial setup command:

    $ make setup
  3. You can know run the site via docker-compose by running the convenience command:

    $ make up

    The site will initially be generated and then the development server will be running in the docker container. You will see the generated _site directory locally. Navigate to http://localhost:4002 in your browser to connect the livereload feature and view the site.

    There are a number of commands available. When you are done developing, it is recommended to shut down the docker container via make down. If you need to enter the container for debug, run make debug, and so forth. Read through the Makefile for additional commands.

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

  4. Make your changes. You can develop locally and changes will be reflected in the container via the shared volume. You may also choose develop with vim or an editor of your choice directly in the container by running:

    $ docker-compose exec site bash
  5. View your changes in the browser.

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

TIP - Sometimes Jekyll gets confused and seems to be out-of-sync. This might happen, for example, when you pull from master and lots of files have moved. The Jekyll --incremental serve option can also sometimes produce this. To fix this run:

$ make down && make clean && make up

In some rare cases you may want to force all running containers down with:

$ docker rm -f $(docker ps -aq)

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 will also regenerate the associated Javascript file in src/assets/js:

$ cd `src/_packages/dartpad_picker
$ ./compile.sh

Deploy to a staging site

You can deploy your local edits to a personal staging site as follows.

  1. If you do not already have a Firebase project, navigate to the Firebase Console and create your own Firebase project (e.g. my-foo). You only need to do this step once.

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

    $ npx firebase init
  3. Tell Firebase about your project with the firebase use command. You only need to do this step once:

    $ 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 staging:

    $ npx firebase use my-foo
    Now using alias staging (my-foo)
  5. Build the site via Docker with:

    $ DISABLE_TESTS=1 make build

    You will see the _site directory has been refreshed locally.

  6. Finally, run the deploy command:

    $ 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:

About

Flutter web site

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • SCSS 37.4%
  • JavaScript 31.1%
  • Shell 9.3%
  • Ruby 7.7%
  • Dart 7.5%
  • Makefile 4.4%
  • Other 2.6%