The Dart language site (www.dartlang.org)

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. But if you want/need to build, here's how.

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

Create or choose a directory to hold this site's Git repository, and the other repositories needed to build this site (which will be fetched later); for example, ~/git.
Clone this repo (site-www) into the chosen directory by following the instructions given in the GitHub help on Cloning a repository.

2.5 (Optional) Clone and setup site-webdev

If you'll be updating code under examples, and you'd like auto refresh code excerpts in this site's pages, then you'll need to clone and setup the site-webdev repo under ~/git.

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:

cd <path-to-this-repo> # change to root of this repo
source ./scripts/env-set.sh # initialize environment variables; install/use required Node & Ruby version
./scripts/before-install.sh # install core set of required tools
./scripts/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 publish folder. To serve this folder use:

superstatic --port 4000

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:

./scripts/serve_local.sh

Site checks

Checking example code

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

./scripts/dartfmt.sh
./scripts/refresh-code-excerpts.sh
./scripts/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, make sure you're using the Firebase server:

jekyll build && firebase serve --port 4000

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

linkcheck :4000

If the link checker crashes:

Make sure you're using the firebase server.
Rerun the command with the -d option to figure out what triggered the crash. (Hint: If the last file read is get-started-flowchart.png, then you're probably running the jekyll server, not the firebase one.)

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://webdev.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:

Select Create New Project.
Enter a project name in the dialog, such as zz-www-dartlang-1.
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.

Checking against the old sitemap

To make sure we are not breaking any links (or bookmarks) from yesteryear, you can take the old sitemap as input for the link checker.

Again, make sure you are running the localhost server (./serve_local.sh), then:

linkcheck :4000 -i deploy/urls/old_site_urls.txt

jyaif / site-www