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

Also see:

• github.com/dart-lang/site-webdev
• github.com/dart-lang/site-events
• github.com/dart-lang/www.dartlang.org (the original www.dartlang.org site, which included information now in webdev.dartlang.org & events.dartlang.org; the repo includes more setup info than we have here)

See Writing for *.dartlang.org.

Contributions welcome! (Just sign our CLA.)

1. If you're on a Mac, install Xcode.

2. Make sure you have Ruby. Consider using rvm to manage Ruby versions.

3. Install npm by installing Node.js; only needed to install firebase tools.

4. Install Firebase:

   npm install -g firebase-tools     # might require sudo
   

5. Install bundles (you might need to run gem install bundler first):

   bundle install
   

6. Install the linkcheck tool

   pub global activate linkcheck
   

   Follow the instructions provided by pub global to put the linkcheck command on your path.

While you're working on the site, the best way to see your changes is to run the provided script, which runs jekyll build --watch and firebase serve --port 4000 in parallel.

In terminal, run:

./serve_local.sh

Navigate to localhost:4000; webdev is served from localhost:4001.

Since we host on Firebase, using the Firebase server makes sure everything works as closely to production as possible. Firebase hosting behaves very differently from Jekyll's WEBrick server, and our redirects in firebase.json obviously only work with Firebase.

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

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.

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