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.
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.
- Clone this repo and its submodule at the same, use the
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:
cd <path-to-webdev-repo># change to root of this repo, e.g.:
source ./tool/env-set.sh# initialize environment variables; install/use required Node & Ruby version
./tool/before-install.sh# install core set of required tools
./tool/install.sh# install everything else needed to build this site
- 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:
npx gulp build --dartdoc# full site build including API docs
The generated site is placed in the
publish folder. To serve this folder use:
npx superstatic --port 4001
Or, if you aren't testing redirects, use this command (which has the bonus of autorefreshing your browser after edits):
jekyll serve --livereload
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:
jekyll | Error: Too many open filesunder MacOS or Linux? One way to resolve this is to add the following to your
ulimit -n 8192
and then reboot your machine.
If you'd like to separately build and then serve, the commands are:
npx gulp build --no-dartdoc# build site without regenerating API docs
npx superstatic --port 4001# serve site under
npx gulp build options include:
publishand file fragments (nothing else)
--[no-]dartdoc[=all|acx|ng|forms|router|test]# generates API docs for named packages (default
--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:
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):
source ./tool/env-set.sh # reset environment vars and (re-)install Node & Ruby npx gulp clean # clean out all temporary site folders npx gulp build --dartdoc # full site regeneration ./tool/serve.sh
If you are still having build problems, you might need to once again step through the installation instructions.
Deploy to the
default firebase project (hosting the official site) using this
./tool/shared/deploy.sh --robots ok default
Other useful Gulp tasks
npx gulp clean && npx gulp build --dartdoc # do a full build from a clean slate npx gulp git-clean-src # WARNING WARNING WARNING: this runs `git clean -xdf src`, # so you'll lose uncommitted work under `src`!