8000 GitHub - ipcjs/flutter-website: Flutter documentation web site
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

ipcjs/flutter-website

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5,611 Commits
.devcontainer
.devcontainer
 
 
.github
.github
 
 
diagrams
diagrams
 
 
examples
examples
 
 
flutter @ 796c8ef
flutter @ 796c8ef
 
 
site-shared @ 2a1ef2b
site-shared @ 2a1ef2b
 
 
src
src
 
 
tool
tool
 
 
.dockerignore
.dockerignore
 
 
.firebaserc
.firebaserc
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.gitmodules
.gitmodules
 
 
AUTHORS
AUTHORS
 
 
CODEOWNERS
CODEOWNERS
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
Dockerfile
Dockerfile
 
 
Gemfile
Gemfile
 
 
Gemfile.lock
Gemfile.lock
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
_config.yml
_config.yml
 
 
_config_dev.yml
_config_dev.yml
 
 
_config_stage.yml
_config_stage.yml
 
 
analysis_options.yaml
analysis_options.yaml
 
 
build.excerpt.yaml
build.excerpt.yaml
 
 
docker-compose.yml
docker-compose.yml
 
 
firebase.json
firebase.json
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
pubspec.yaml
pubspec.yaml
 
 

Repository files navigation

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:

About

Flutter documentation web site

docs.flutter.dev

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Dart 89.3%
  • SCSS 5.5%
  • JavaScript 2.0%
  • Ruby 1.3%
  • Shell 1.0%
  • Makefile 0.6%
  • Dockerfile 0.3%
0