The Dart language site (www.dartlang.org)
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.)
-
If you're on a Mac, install Xcode.
-
Make sure you have Ruby. Consider using rvm to manage Ruby versions.
-
Install
npm
by installing Node.js; only needed to install firebase tools. -
Install Firebase:
npm install -g firebase-tools # might require sudo
-
Install bundles (you might need to run
gem install bundler
first):bundle install
-
Install the
linkcheck
toolpub global activate linkcheck
Follow the instructions provided by
pub global
to put thelinkcheck
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:
- 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
.
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