dart-lang/site-webdev

Name: site-webdev

Owner: Dart

Description: Source for webdev.dartlang.org

Created: 2016-07-11 17:58:14.0

Updated: 2018-05-24 19:24:48.0

Pushed: 2018-05-24 19:27:26.0

Homepage: https://webdev.dartlang.org/

Size: 24261

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Site for Dart for the web (webdev.dartlang.org)

The webdev.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
• Chrome v63 or later.

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-webdev), 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-webdev.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   # change to root of this repo, e.g.: ~/git/site-webdev
2. source ./scripts/env-set.sh   # initialize environment variables; install/use required Node & Ruby version
3. ./scripts/before-install.sh   # install core set of required tools
4. ./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:

• gulp build --dartdoc   # full site build including API docs

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

• superstatic --port 4001

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

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

• ./scripts/serve_local.sh

NOTE: Getting jekyll | Error:  Too many open files under MacOS or Linux? One way to resolve this is to add the following to your .bashrc:

 ulimit -n 8192

and then reboot your machine.

If you'd like to separately build and then serve, the commands are:

• gulp build --no-dartdoc   # build site without regenerating API docs
• superstatic --port 4001   # serve site under publish

Some gulp build options include:

• --clean   # deletes publish and file fragments (nothing else)
• --[no-]dartdoc[=all|acx|ng|forms|router|test]   # generates API docs for named packages (default all)
• --use-cached-api-doc   # will use cached API docs rather than regenerate them; without this option API docs are regenerated afresh each time
• --fast   # skips some one-time setup tasks (can spead up repeated builds)
• --log=x   # logging level: debug, info, warn (default), error

Rebuilding this site from scratch

If you encounter build problems, or if you haven't build this site in a while, you might want to rebuild it from scratch, doing all of the following steps (in order):

ce ./scripts/env-set.sh  # reset environment vars and (re-)install Node & Ruby
 clean                   # clean out all temporary site folders
 build --dartdoc         # full site regeneration
ripts/serve_local.sh

If you are still having build problems, you might need to once again step through the installation instructions.

Other useful Gulp tasks

 clean && gulp build --dartdoc  # do a full build from a clean slate
 build-deploy                   # build & deploy to active firebase project
 git-clean-src  # WARNING WARNING WARNING: this runs `git clean -xdf src`,
                # so you'll lose uncommitted work under `src`!

Prepping for Dart 2.0

Please add the following comment to docs that will need updating for Dart 2.0. We're doing what we can now, but some things are not yet ready.

{% comment %}
update-for-dart-2
{% endcomment %}