Source for Dart website
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
deploy Use default Jekyll destination folder name _site; share more installa… Sep 6, 2018
examples Make clear that const constructors don't always create constant objec… Sep 10, 2018
examples_archive Update the dart:io article (#1110) Sep 5, 2018
site-shared @ 82fa703 Improve page GitHub buttons a11y, and tweak styling (#1151) Sep 12, 2018
src Update /guides/libraries/useful-libraries (#1155) Sep 14, 2018
tool Use default Jekyll destination folder name _site; share more installa… Sep 6, 2018
.firebaserc chore: add firebase dartlang-org-staging-1 project (#726) Mar 30, 2018
.gitignore Use default Jekyll destination folder name _site; share more installa… Sep 6, 2018
.gitmodules Rename `./scripts` -> `./tool`; use only local npm packages (#1133) Sep 6, 2018
.travis.yml Travis: fix path to new deploy script Sep 6, 2018
AUTHORS Migrating repo from Ocupop Jul 11, 2016
CONTRIBUTING.md Update CONTRIBUTING.md Jun 7, 2018
Gemfile Ensure main nav dropdown and its divider are properly displayed (#1121) Sep 4, 2018
Gemfile.lock Ensure main nav dropdown and its divider are properly displayed (#1121) Sep 4, 2018
LICENSE Migrating repo from Ocupop Jul 11, 2016
README.md Use default Jekyll destination folder name _site; share more installa… Sep 6, 2018
_config.yml Move GitHub page buttons to site-shared (#1149) Sep 12, 2018
_config_dev.yml Refreshed look with new logos (#830) May 3, 2018
_config_now.yml Upgrade to bootstrap 4, Step 1: essentials (#1106) Aug 27, 2018
build.excerpt.yaml chore: use new code excerpter (#912) Jun 9, 2018
firebase.json chore: Add redirects for common 404s (#1156) Sep 14, 2018
package.json Rename `./scripts` -> `./tool`; use only local npm packages (#1133) Sep 6, 2018
pubspec.yaml Dart 2 stable (#1041) Aug 6, 2018

README.md

The Dart language site (www.dartlang.org)

Build Status SVG first-timers SVG

The www.dartlang.org site, built with Jekyll and hosted on Firebase.

We welcome contributions, and we're first-timer friendly!

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 build this site

1. Get the prerequisites

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

  • nvm, the Node Version Manager.
  • rvm, the Ruby Version Manager.
  • Dart

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

2. Clone this repo and its submodule

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

To clone this repo (site-www), follow the instructions given in the GitHub help on Cloning a repository, and choose one of the following submodule-cloning techniques:

  • Clone this repo and its submodule at the same, use the --recurse-submodules option:
    git clone --recurse-submodules https://github.com/dart-lang/site-www.git
  • If you've already cloned this repo without its submodule, then run this 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

3. Run installation scripts

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

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

  1. cd <path-to-this-repo>   # change to root 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 a new terminal/command window to work on this repo, repeat steps 1 and 2 above.
  • If you upgrade Dart then rerun all of the steps above.

Building this site

Once everything is installed, you need to do a full site build at least once:

  • jekyll build   # full site build

The generated site is placed in the _site folder. To serve this folder use:

  • npx superstatic --port 4000

Or, if you aren't testing redirects, use this command (which has the bonus of autorefreshing your browser after edits):

  • jekyll serve --livereload

To view the generated site open localhost:4000 in a browser.

You can build, serve, and have a watcher for changes by running the following command:

  • ./tool/serve.sh

Pre-push checks

If you've made changes to this site's documentation and committed locally, then run the following command before pushing your work:

./tool/pre-push.sh

If the script reports errors or warnings, then address the issues and rerun the script. Otherwise, you can push your changes.

Site checks

Checking example code

If you've made changes to the example code run the following commands:

  • ./tool/dartfmt.sh
  • ./tool/refresh-code-excerpts.sh
  • ./tool/analyze-and-test-examples.sh -q

If the last command reports failed tests and you'd like to know which test failed, then rerun the command without the -q flag.

Checking the site's HTML

First, build the site and launch the server:

jekyll build && npx superstatic --port 4000

Next, to check for broken links, run this from the top of the repo:

linkcheck :4000

To also check external URLs (which is much slower), run the linkcheck command with the --external (or -e, for short) option.

With this tool you can check any URL by simply specifying it as a parameter:

linkcheck https://www.dartlang.org

To check for valid HTML, good images, and broken links (though not as well as linkcheck.dart), run this from the top of the repo:

./deploy/html_proof.rb

Staging the site

First, save your changes. For example, from the top directory:

git commit src

Create a pull request by pushing your branch to GitHub.

git push origin <branchname>

Navigate to the Firebase console, console.firebase.google.com.

If you don't already have a project to stage to, create it:

  1. Select Create New Project.
  2. Enter a project name in the dialog, such as zz-www-dartlang-1.
  3. Click Create Project. This takes you to the page for your new project.

Note: To keep the number of projects under control, we reuse them. Our naming convention is <first initial><last initial>-www-dartlang-<number>, for example, sz-www-dartlang-1 and kw-www-dartlang-1. For webdev.org, replace www with webdev.

Return to the Firebase console. You should now see your project in the list. Copy the name of your project (e.g. sz-www-dartlang-2) to your clipboard.

On the command line, from the top of GitHub repo, edit the .firebaserc file.

Change www-dartlang-org to the name of your project. For example:

{
  "projects": {
    "default": "sz-www-dartlang-2"
  }
}

Build the docs, to get the latest changes and set the new project name:

jekyll build

Then deploy the docs:

firebase deploy

You can now navigate to the staged version at https://<your-instance>.firebaseapp.com/—for example, https://sz-www-dartlang-2.firebaseapp.com/.

Important: Don't commit the .firebaserc file containing the name of your staged version.

Navigate to the PR on GitHub and update the it with the location of the staged version, the names of your reviewers, and so on.

Before making any more changes, stash .firebaserc:

git stash

You can later retrieve the stashed file, if you need to stage again, using git stash pop.