Dart Website (dartlang.org)

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

To give us feedback, please file issues on GitHub.

Contributions welcome! (Just sign our CLA.) Details on processes, formatting, and style are in Writing for dartlang.org. You can fork and submit patches at https://github.com/dart-lang/dartlang.org.

Orientation

./src

All the working files.

./src/appengine

App engine configuration files.

./src/diagrams

Omnigraffle files, mostly. We don't publish these on the site, but we need to keep them around in case we need to edit a diagram or create a similar diagram.

./src/site

Documents, HTML files, images, etc. You work out of here normally.

./src/tests

Code that's featured in the site's pages, placed here so it can be tested automatically without being copied to the site.

./build

Generated by Jekyll, to be deployed to server. This directory is transient; you can delete it.

Configuring your system

• If you're using a Mac, make sure you have Xcode.
• Ensure you have Ruby 1.9.3 or 2.0.
• Ensure you have Python 2.7.
• In a terminal, from the dartlang.org project root:
  1. Run sudo gem install fast-stemmer -v '1.0.2'
  2. Run sudo gem install bundler
  3. Run bundle install, which installs the gems listed in Gemfile (liquid, jekyll, etc.).
• Get the Dart SDK, if you don't already have it, and make sure pub is in your path.
• Download and install the Google App Engine SDK for Python
• Ask an admin to invite you to modify the Dart project on the Google App Engine.

Tips for Mac

• You might want the binary install of Python 2.7.3
• Ensure App Engine is using Python 2.7. You will see "you're using 2.6" in the log if it is not.
  • You can go to Preferences and enter the direct path to the Python 2.7 binary. For example: /Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7.

Tips for Windows

• Install Python with the Windows installer.
• Install Ruby with the RubyInstaller site.
• Install the Ruby DevKit from the RubyInstaller site
• Run gem install bundler.
• Run bundle install from the root of your dartlang project.

GitHub setup

• Create a GitHub login login if you don't already have one.
• Ask an admin to invite you to the dart-lang project on GitHub.

Contributing via Chromium Code Review

On a Mac:

• Make sure you have Xcode (contains git)
• Install depot_tools: $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
• Add depot_tools to your PATH: $ export PATH="$PATH":pwd/depot_tools NOTE: You may want to add this to your .bashrc file or your shell's equivalent so that you don’t need to reset your $PATH manually each time you open a new shell.
• Run git cl config. For the Rietveld server, specify https://chromiumcodereview.appspot.com.
  • If you haven't used http://chromiumcodereview.appspot.com/ before, you'll be asked to specify an app-specific password. Go ahead and create one. Your regular password won't work.

Development

• Open a terminal to the root of this project.
• Run the server with make server, and leave it running while you edit files.
• Your web browser opens to http://localhost:8081.
  • You may need to reload once.
• Edit, create docs as normal.
• To run tests, run ./runtests.sh.

Note: If you see single-page breadcrumbs on pages such as http://localhost:8081/tools/pub/cmd/pub-build.html, make sure that you've installed the latest gem versions. (Run sudo bundle install and then bundle install.)

Windows development tips

You probably won't have make available on the command line by default.

• To just get up and running, run jekyll from the src/site folder.
• This starts up the Jekyll webserver and generates into build/static.
• If Jekyll does not generate output, you need to type chcp 65001 at the command prompt to change the code page to UTF-8. (Jekyll fails silently if this is not done.)
• To clean, simply delete the contents of build/static and restart jekyll.

Testing

There are a variety of tests you can run:

Release Testing

There is a sanity-test target that tests some very basic features of dartlang.org with some browser tests:

# launch the local copy of dartlang.org with `jekyll serve`, and test it:
make sanity-test

# test against the live dartlang.org site:
make sanity-test-live

# test against any staged copy of dartlang.org:
bundle exec ruby src/tests/site/sanity.rb <URL>

Deploying the site

• Run make clean && make deploy.
  • This builds the site and places everything into build/, and then deploys the site. (Note: You can also run make clean && make build and then deploy manually using App Engine.)
  • This command uses the current branch for the App Engine version name.
• You will probably need to generate an App-specific password. Save this password into the App Engine Launcher during the first deployment.

Regenerating Dartisans playlists

Did you just run a Dartisans? Good for you! Here's what you need to do:

1. Update the description to be present tense (instead of future), and remove the link to the moderator page.
2. Ensure the episode is added to the Dartisans playlist, owned by Google Developers channel.
3. Sort the playlist by date.
4. Ensure your episode explicitly sets a Recorded On date.
5. Format your episode's title like this: "Dartisans ep. XX: Subtitle Here"
6. Pick a great image thumbnail. Don't use the static Dart logo.
7. Now run make dartisansplaylist
8. Test it, commit, and go!

Updating the book

The files under docs/dart-up-and-running/contents are autogenerated from the DocBook files for Dart: Up and Running. Here's how to update these files.

First, prepare:

• Make sure dart (the Dart VM) is in your PATH.

    > which dart
    /Users/me/dart/dart-sdk/bin/dart
  

• Make sure xsltproc is in your PATH.

    > which xsltproc
    /usr/bin/xsltproc
  

• Find a copy of the latest .xml files that make up dart-up-and-running. For example:

    > ls ~/Dart/dartbook/GITHUB
    LICENSE   bookinfo.xml  ch02.xml  ch05.xml  figs
    README.md ch00.xml  ch03.xml  code    foreword.xml
    book.xml  ch01.xml  ch04.xml  colo.xml
  

Now you're ready. From the top directory of this repo, run the following command, specifying the directory that contains ch*.xml:

make book BOOK_XML_DIR=<dir-with-xml-files>

For example:

make book BOOK_XML_DIR=~/Dart/dartbook/GITHUB

Wait 4-5 minutes for results.

Very carefully check the diffs, paying special attention to the headers at the top. Rerun the make book command if you aren't sure of the changes.

(Yes, different runs of make book can have different results, even when the .xml files haven't changed. The problem I've noticed has been misnaming files or skipping them in the navigation. Reported as dartbug.com/8128.)