diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json deleted file mode 100644 index fe1a31ef97..0000000000 --- a/.devcontainer/devcontainer.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "Dart.dev", - "dockerComposeFile": "../docker-compose.yml", - "extensions": [ - "dart-code.dart-code" - ] -} \ No newline at end of file diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index aa19d21c20..0000000000 --- a/.dockerignore +++ /dev/null @@ -1,6 +0,0 @@ -AUTHORS -CONTRIBUTING.md -LICENSE -README.md -deploy/ -.github/ \ No newline at end of file diff --git a/.github/dependabot.yml b/.github/dependabot.yml index f0cca6b169..67df0aa4e6 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -3,14 +3,6 @@ version: 2 updates: - - package-ecosystem: "bundler" - directory: "/" - schedule: - interval: "daily" - labels: - - "auto.dependencies" - - "auto.bundler" - - "lang.ruby" - package-ecosystem: "docker" directory: "/" schedule: diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index d5b32ebcf7..70ef61b97d 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -23,7 +23,7 @@ jobs: strategy: fail-fast: false matrix: - language: [ 'javascript', 'ruby' ] + language: [ 'javascript' ] # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ] # Learn more about CodeQL language support at https://git.io/codeql-language-support diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b7c46d2e82..a8a8479567 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -43,7 +43,7 @@ jobs: - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3 with: sdk: ${{ matrix.sdk }} - - name: Fetch packages + - name: Fetch Dart packages run: dart pub get - name: Check Dart code formatting run: dart run dart_site format-dart --check @@ -57,25 +57,42 @@ jobs: linkcheck: name: Build site and check links runs-on: ubuntu-latest - strategy: - fail-fast: false steps: - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 with: submodules: recursive - - run: make build - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3 with: sdk: stable - - name: Fetch packages + - name: Fetch Dart packages run: dart pub get - - name: Check for broken Markdown links - run: dart run dart_site check-link-references - - name: Validate the firebase.json file - run: dart run dart_site verify-firebase-json - - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 + - uses: pnpm/action-setup@ebcfd6995dade4b0104ac774445cef8b3b4635b0 + with: + version: 8 + - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 with: node-version: ${{ env.NODE_VERSION }} - - run: npm install -g firebase-tools@13.0.2 + cache: 'pnpm' + - name: Install node dependencies + run: pnpm install + - name: Build site + run: dart run dart_site build + - name: Check for broken Markdown links + run: dart run dart_site check-link-references - name: Check internal site links are functional run: dart run dart_site check-links + + firebase-validate: + name: Validate Firebase configuration + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 + with: + submodules: recursive + - uses: dart-lang/setup-dart@ca7e6fee45ffbd82b555a7ebfc236d2c86439f5b + with: + sdk: stable + - name: Fetch Dart packages + run: dart pub get + - name: Validate the firebase.json file + run: dart run dart_site verify-firebase-json diff --git a/.gitignore b/.gitignore index 33872d381a..2688f6a9e8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,3 @@ -_asset_bundler_cache -_bookhtml _cache/ _site/ .*-cache @@ -10,8 +8,6 @@ _site/ .env* .firebase .idea -.packages -.pub .spelling .vscode *.cache @@ -25,6 +21,7 @@ build firebase-debug.log node_modules pubspec.lock +package-lock.json tmp # Misc diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000000..b009dfb9d9 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +lts/* diff --git a/AUTHORS b/AUTHORS index db3e06f6cf..ac3fca804b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -13,3 +13,4 @@ Chris Buckett Michael Haubenwallner Victor Berchet Pradumna Saraf +Parker Lougheed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7633179a4..971036774b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,7 @@ You can contribute in a few ways. * **[Report issues][].** -* **Fix known issues** (especially ones with the label **[help wanted][]** or - **[beginner][]**). These issues may or may not be easy to fix. Sometimes +* **Fix known issues.** These issues may or may not be easy to fix. Sometimes they're issues that we don't have the expertise to fix, and we'd love to work with a contributor who has the right skills. @@ -37,11 +36,9 @@ More info: * For more ways to contribute to Dart, see the [dart-lang/sdk Contributing page][]. -[beginner]: https://github.com/dart-lang/site-www/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22%20label%3Abeginner%20 [dart-lang/sdk Contributing page]: https://github.com/dart-lang/sdk/blob/main/CONTRIBUTING.md -[GitHub pull request]: https://docs.github.com/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests +[GitHub pull request]: https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests [Google Developer Documentation Style Guide]: https://developers.google.com/style/ -[help wanted]: https://github.com/dart-lang/site-www/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22help%20wanted%22%20 [in the site-shared repo]: https://github.com/dart-lang/site-shared/blob/main/doc [issue tracker]: https://github.com/dart-lang/site-www/issues [on Flutter's Discord server]: https://github.com/flutter/flutter/wiki/Chat @@ -62,29 +59,35 @@ you'll probably need to change the code in two places: For example, say you want to change the following code in the [Variables documentation](https://dart.dev/language/variables): -``` +```` -{% prettify dart tag=pre+code %} +```dart var name = 'Bob'; -{% endprettify %} ``` +```` Besides editing -[/src/language/variables.md][] +[`/src/language/variables.md`][] (which you can find by clicking the GitHub icon at the top right of the page), you'll also need to edit the `var-decl` region of -[/examples/misc/lib/language_tour/variables.dart][]. +[`/examples/misc/lib/language_tour/variables.dart`][]. If you create a PR but forget to edit the Dart file, or if your changes don't analyze/test cleanly, the [GitHub Actions][] CI build will fail. Just update the PR, and GitHub Actions will run again. +If you followed the setup in the README, +you can instead run `dart run dart_site refresh-excerpts` +from the root directory of the repository to update the Markdown files. + [GitHub Actions]: https://docs.github.com/actions/learn-github-actions/understanding-github-actions -[/src/language/variables.md]: https://github.com/dart-lang/site-www/blob/main/src/language/variables.md -[/examples/misc/lib/language_tour/variables.dart]: https://github.com/dart-lang/site-www/blob/main/examples/misc/lib/language_tour/variables.dart +[`/src/language/variables.md`]: https://github.com/dart-lang/site-www/blob/main/src/language/variables.md +[`/examples/misc/lib/language_tour/variables.dart`]: https://github.com/dart-lang/site-www/blob/main/examples/misc/lib/language_tour/variables.dart ## A word about conduct We pledge to maintain an open and welcoming environment. -For details, see our [code of conduct](https://dart.dev/community/code-of-conduct). +For details, see our [code of conduct][]. + +[code of conduct]: https://dart.dev/community/code-of-conduct diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 8725e05508..0000000000 --- a/Dockerfile +++ /dev/null @@ -1,154 +0,0 @@ -FROM ruby:3.2.3-slim-bookworm@sha256:97fccffe954d1e0c7fa6634020379417d67435a7f9a7c10b6ef3f49e498307e6 as base - -ENV DEBIAN_FRONTEND=noninteractive -ENV TZ=US/Pacific -RUN apt update && apt install -yq --no-install-recommends \ - build-essential \ - ca-certificates \ - curl \ - git \ - gnupg \ - lsof \ - make \ - unzip \ - && rm -rf /var/lib/apt/lists/* - -RUN echo "alias lla='ls -lAhG --color=auto'" >> ~/.bashrc -WORKDIR /root - - -# google-chrome-stable - - -# ============== DART ============== -# See https://github.com/dart-lang/dart-docker -# See https://github.com/dart-lang/setup-dart/blob/main/setup.sh -FROM base as dart -ARG DART_VERSION=latest -ARG DART_CHANNEL=stable -ENV DART_VERSION=$DART_VERSION -ENV DART_CHANNEL=$DART_CHANNEL -ENV DART_SDK=/usr/lib/dart -ENV PATH=$DART_SDK/bin:$PATH -RUN set -eu; \ - case "$(dpkg --print-architecture)_${DART_CHANNEL}" in \ - # BEGIN dart-sha - amd64_stable) \ - DART_SHA256="e35e66f6cb5f511eb909fc27f9cebe81712925b6abd4494310003cdf26410ab1"; \ - SDK_ARCH="x64";; \ - arm64_stable) \ - DART_SHA256="aa840a615e90fc26ca0ca348be8359b254a144cff6a0e2c3f7eb361ed9aef393"; \ - SDK_ARCH="arm64";; \ - amd64_beta) \ - DART_SHA256="a7ed5168acabce7cfb292de210d5fedb33a481548470a6e8142b20946ca81cfb"; \ - SDK_ARCH="x64";; \ - arm64_beta) \ - DART_SHA256="e9516c29f1261dd985685a0d1e68ec85c531795e6aed6d7da72604a9a978e9b9"; \ - SDK_ARCH="arm64";; \ - amd64_dev) \ - DART_SHA256="6f43abe4c8ad3a82b4048c80fe71edff99aeb5497af4a13f66c31170db311ab6"; \ - SDK_ARCH="x64";; \ - arm64_dev) \ - DART_SHA256="69493b600f1338bd955b24446143a8c9426784d8ea2b779a3450d65034cbebfc"; \ - SDK_ARCH="arm64";; \ - # END dart-sha - esac; \ - SDK="dartsdk-linux-${SDK_ARCH}-release.zip"; \ - BASEURL="https://storage.googleapis.com/dart-archive/channels"; \ - URL="$BASEURL/$DART_CHANNEL/release/$DART_VERSION/sdk/$SDK"; \ - curl -fsSLO "$URL"; \ - unzip "$SDK" > /dev/null && mv dart-sdk "$DART_SDK" && rm "$SDK"; -ENV PUB_CACHE="${HOME}/.pub-cache" -RUN dart --disable-analytics -RUN echo -e "Successfully installed Dart SDK:" && dart --version - - -# ============== NODEJS INSTALL ============== -FROM dart as node - -RUN mkdir -p /etc/apt/keyrings \ - && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \ - && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \ - && apt-get update -yq \ - && apt-get install nodejs -yq \ - && npm install -g npm # Ensure latest npm - - -# ============== DEV/JEKYLL SETUP ============== -FROM node as dev -WORKDIR /app - -ENV JEKYLL_ENV=development -ENV RUBY_YJIT_ENABLE=1 -COPY Gemfile Gemfile.lock ./ -RUN gem update --system && gem install bundler -RUN BUNDLE_WITHOUT="test production" bundle install --jobs=4 --retry=2 - -ENV NODE_ENV=development -COPY package.json package-lock.json ./ -RUN npm install -g firebase-tools@13.0.2 -RUN npm install - -COPY ./ ./ - -# Ensure packages are still up-to-date if anything has changed -# RUN dart pub get --offline -RUN dart pub get - -# Let's not play "which dir is this" -ENV BASE_DIR=/app -ENV TOOL_DIR=$BASE_DIR/tool - -# Jekyl -EXPOSE 4000 -EXPOSE 35729 - -# Firebase emulator port -# Airplay runs on :5000 by default now -EXPOSE 5500 - -# re-enable defult in case we want to test packages -ENV DEBIAN_FRONTEND=dialog - - -# ============== FIREBASE EMULATE ============== -FROM dev as emulate -RUN bundle exec jekyll build --config _config.yml,_config_test.yml -CMD ["make", "emulate"] - - -# ============== BUILD PROD JEKYLL SITE ============== -FROM node AS build -WORKDIR /app - -ENV JEKYLL_ENV=production -ENV RUBY_YJIT_ENABLE=1 -COPY Gemfile Gemfile.lock ./ -RUN gem update --system && gem install bundler -RUN BUNDLE_WITHOUT="test development" bundle install --jobs=4 --retry=2 --quiet - -ENV NODE_ENV=production -COPY package.json package-lock.json ./ -RUN npm install - -COPY ./ ./ - -RUN dart pub get - -ENV BASE_DIR=/app -ENV TOOL_DIR=$BASE_DIR/tool - -ARG BUILD_CONFIGS=_config.yml -ENV BUILD_CONFIGS=$BUILD_CONFIGS -RUN bundle exec jekyll build --config $BUILD_CONFIGS - - -# ============== DEPLOY to FIREBASE ============== -FROM build as deploy -RUN npm install -g firebase-tools@13.0.2 -ARG FIREBASE_TOKEN -ENV FIREBASE_TOKEN=$FIREBASE_TOKEN -ARG FIREBASE_PROJECT=default -ENV FIREBASE_PROJECT=$FIREBASE_PROJECT -RUN [[ -z "$FIREBASE_TOKEN" ]] && echo "FIREBASE_TOKEN is required for container deploy!" -RUN make deploy-ci diff --git a/Gemfile b/Gemfile deleted file mode 100644 index 5e342f63b6..0000000000 --- a/Gemfile +++ /dev/null @@ -1,12 +0,0 @@ -source "https://rubygems.org" - -gem 'activesupport', '~> 7.1.3' -gem 'jekyll', '4.3.3' -gem 'jekyll-sass-converter', '~> 3.0.0' -gem 'kramdown-parser-gfm' -gem 'liquid-tag-parser', '~> 2.0.2' -gem 'webrick' - -group :jekyll_plugins do - gem 'jekyll-toc', '~> 0.18.0' -end diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index 6a06ca575a..0000000000 --- a/Gemfile.lock +++ /dev/null @@ -1,123 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - activesupport (7.1.3) - base64 - bigdecimal - concurrent-ruby (~> 1.0, >= 1.0.2) - connection_pool (>= 2.2.5) - drb - i18n (>= 1.6, < 2) - minitest (>= 5.1) - mutex_m - tzinfo (~> 2.0) - addressable (2.8.6) - public_suffix (>= 2.0.2, < 6.0) - base64 (0.2.0) - bigdecimal (3.1.6) - colorator (1.1.0) - concurrent-ruby (1.2.3) - connection_pool (2.4.1) - drb (2.2.0) - ruby2_keywords - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - eventmachine (1.2.7) - extras (0.3.0) - forwardable-extended (~> 2.5) - ffi (1.16.3) - forwardable-extended (2.6.0) - google-protobuf (3.25.2) - google-protobuf (3.25.2-aarch64-linux) - google-protobuf (3.25.2-x86_64-linux) - http_parser.rb (0.8.0) - i18n (1.14.1) - concurrent-ruby (~> 1.0) - jekyll (4.3.3) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (~> 1.0) - jekyll-sass-converter (>= 2.0, < 4.0) - jekyll-watch (~> 2.0) - kramdown (~> 2.3, >= 2.3.1) - kramdown-parser-gfm (~> 1.0) - liquid (~> 4.0) - mercenary (>= 0.3.6, < 0.5) - pathutil (~> 0.9) - rouge (>= 3.0, < 5.0) - safe_yaml (~> 1.0) - terminal-table (>= 1.8, < 4.0) - webrick (~> 1.7) - jekyll-sass-converter (3.0.0) - sass-embedded (~> 1.54) - jekyll-toc (0.18.0) - jekyll (>= 3.9) - nokogiri (~> 1.12) - jekyll-watch (2.2.1) - listen (~> 3.0) - kramdown (2.4.0) - rexml - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - liquid (4.0.4) - liquid-tag-parser (2.0.2) - extras (~> 0.3) - liquid (>= 3.0, < 5.0) - listen (3.8.0) - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - mercenary (0.4.0) - mini_portile2 (2.8.5) - minitest (5.21.2) - mutex_m (0.2.0) - nokogiri (1.16.2) - mini_portile2 (~> 2.8.2) - racc (~> 1.4) - nokogiri (1.16.2-aarch64-linux) - racc (~> 1.4) - nokogiri (1.16.2-x86_64-linux) - racc (~> 1.4) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (5.0.4) - racc (1.7.3) - rake (13.1.0) - rb-fsevent (0.11.2) - rb-inotify (0.10.1) - ffi (~> 1.0) - rexml (3.2.6) - rouge (4.2.0) - ruby2_keywords (0.0.5) - safe_yaml (1.0.5) - sass-embedded (1.70.0) - google-protobuf (~> 3.25) - rake (>= 13.0.0) - sass-embedded (1.70.0-aarch64-linux-gnu) - google-protobuf (~> 3.25) - sass-embedded (1.70.0-x86_64-linux-gnu) - google-protobuf (~> 3.25) - terminal-table (3.0.2) - unicode-display_width (>= 1.1.1, < 3) - tzinfo (2.0.6) - concurrent-ruby (~> 1.0) - unicode-display_width (2.5.0) - webrick (1.8.1) - -PLATFORMS - aarch64-linux - ruby - x86_64-linux - -DEPENDENCIES - activesupport (~> 7.1.3) - jekyll (= 4.3.3) - jekyll-sass-converter (~> 3.0.0) - jekyll-toc (~> 0.18.0) - kramdown-parser-gfm - liquid-tag-parser (~> 2.0.2) - webrick - -BUNDLED WITH - 2.5.5 diff --git a/Makefile b/Makefile deleted file mode 100644 index f307a9548d..0000000000 --- a/Makefile +++ /dev/null @@ -1,125 +0,0 @@ -#!/usr/bin/make -f --include .env - - -all: clean up down shell serve test-build test-run run setup \ - serve emulate stage test build-image build deploy deploy-ci - -.PHONY: all -.DEFAULT_GOAL := up - -# NOTE all vars can be overridden by using a local .env file -BUILD_COMMIT := $(shell git rev-parse --short HEAD) -BUILD_CONFIGS ?= _config.yml -BUILD_NAME ?= dart_dev_build -BUILD_TAG ?= dart-dev -BUILD_TARGET ?= build -DART_CHANNEL ?= stable -DART_VERSION ?= latest -FIREBASE_PROJECT ?= default -FIREBASE_CHANNEL ?= dart -JEKYLL_SITE_HOST ?= 0.0.0.0 -JEKYLL_SITE_PORT ?= 4000 - -# Here so Docker Compose does not complain, add any env -# overrides to this file. Blank is okay, it's ignored. -# For example, add a FIREBASE_PROJECT if staging -.env: - touch $@ - -# Clean up caches, build files, etc -clean: - rm -rf _site **/.jekyll* *.log tmp .dart_tool - -# Start local dev container/server -up: - docker compose up site - -# Bring down the local dev container/server -down: - -docker compose down site - -# Run the dev container and enter shell for debugging -run: - docker compose run --rm site bash - -# Enter the shell of the running container from `make up` -exec: - -docker compose exec site bash - -# Reset, build dev container from scratch -setup: - make clean - -docker compose down - -docker rmi ${BUILD_TAG}:${DART_CHANNEL} - docker compose build --no-cache site \ - --build-arg DART_VERSION=${DART_VERSION} \ - --build-arg DART_CHANNEL=${DART_CHANNEL} - -# Serve the Jekyll site with livereload and incremental builds -serve: - bundle exec jekyll serve \ - --host ${JEKYLL_SITE_HOST} \ - --port ${JEKYLL_SITE_PORT} \ - --config _config.yml,_config_dev.yml \ - --livereload \ - --incremental \ - --trace - -# Build docker image with optional target -# Usage: `make build-image [BUILD_CONFIGS=]` -build-image: - DOCKER_BUILDKIT=1 docker build \ - -t ${BUILD_TAG}:${BUILD_COMMIT} \ - --no-cache \ - --target ${BUILD_TARGET} \ - --build-arg DART_VERSION=${DART_VERSION} \ - --build-arg DART_CHANNEL=${DART_CHANNEL} \ - --build-arg BUILD_CONFIGS=${BUILD_CONFIGS} . - -# Build the Jekyll site via Docker and copy built site to local -build: - make clean - make build-image - docker run --rm -d --name ${BUILD_NAME} -t ${BUILD_TAG}:${BUILD_COMMIT} - docker cp ${BUILD_NAME}:/app/_site _site - docker stop ${BUILD_NAME} - docker rmi -f ${BUILD_TAG}:${BUILD_COMMIT} - -# Overwrite robots.txt with production version -write-prod-robots: - @echo "User-agent: *\nDisallow:\n\nSitemap: https://dart.dev/sitemap.xml" \ - > _site/robots.txt - -# Deploy locally -deploy: -ifeq ("${FIREBASE_PROJECT}", "default") - make write-prod-robots -endif - npx firebase deploy -m ${BUILD_COMMIT} \ - --only hosting \ - --project ${FIREBASE_PROJECT} - -# Deploy to Firebase hosting on CI/CD -# Requires that a `FIREBASE_TOKEN` is set in ENV -deploy-ci: -ifeq ("${FIREBASE_PROJECT}", "default") - make write-prod-robots -endif - npx firebase deploy -m ${BUILD_COMMIT} \ - --only hosting \ - --project ${FIREBASE_PROJECT} \ - --token ${FIREBASE_TOKEN} \ - --debug - -# Deploy to Firebase via a staging channel -# Usage: `make stage [FIREBASE_CHANNEL=]` -stage: - npx firebase hosting:channel:deploy ${FIREBASE_CHANNEL} \ - --project ${FIREBASE_PROJECT} - -# Test hosting locally with Firebase emulator -emulate: - npx firebase emulators:start \ - --only hosting \ - --project ${FIREBASE_PROJECT} diff --git a/README.md b/README.md index 9cf6812271..3c7311ad18 100644 --- a/README.md +++ b/README.md @@ -2,69 +2,91 @@ [![Build Status SVG][]][Repo on GitHub Actions] [![OpenSSF Scorecard SVG][]][Scorecard Results] -[![first-timers SVG][]][first-timers] -The https://dart.dev site, built with [Jekyll][] and hosted on [Firebase][]. +The documentation site for the [Dart programming language](https://dart.dev), +built with [Eleventy][] and hosted on [Firebase][]. -[We welcome contributions](CONTRIBUTING.md), -and we're [first-timer friendly][first-timers]! +We welcome contributions of all kinds! +To set up the site locally, follow the +below guidelines on [Building the site](#build-the-site). +To learn more about contributing to this repository, +check out the [Contributing guidelines](CONTRIBUTING.md). ## Getting started Start by looking for an [issue](https://github.com/dart-lang/site-www/issues) that catches your interest, or create an issue with your proposed change. -Ask for the issue to be assigned to you. +Consider adding a comment to let everyone know that you're working on it, and +feel free to ask any questions you have on the same issue. -To update this site, fork the repo, make your changes, and generate a pull -request. 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. +To update this site, fork the repo, make your changes, +and generate a pull request. +For simple changes (such as style and typo fixes), +you probably don't need to build this site. +Often you can make changes using the GitHub UI. +We can stage the changes automatically in your pull request. -> **NOTE:** If you clone this repo locally, -> see the instructions below on cloning with its submodule. +> [!IMPORTANT] +> If you are cloning this repository locally, +> follow the below instruction on cloning with its submodule. If your change involves code samples, adds/removes pages, or affects navigation, -you'll need to build and test your work before submitting. +do consider building and test your work before submitting. -If you want or need to build, follow the steps below. +If you want or need to build the site, follow the steps below. -> **Help us improve these instructions!** -> If you have any problems getting set up to build or performing the -> actual build, please -> [edit this README](https://github.com/dart-lang/site-www/edit/main/README.md) -> or [file an issue](https://github.com/dart-lang/site-www/issues/new?title=README%20issue) -> (or both). - -## Before you build this site +## Build the site For changes beyond simple text and CSS tweaks, -we recommend building the site. +we recommend running the site locally to +enable an edit-refresh cycle. + +### Get the prerequisites + +Install the following tools to build and develop the site: + +#### Dart + +The latest stable release of Dart is required to build the site +and run its tooling. This can be the Dart included in the Flutter SDK. +If you don't have Dart or need to update, follow the +instructions at [Get the Dart SDK][]. + +If you already have Dart installed, verify it's on your path +and already the latest stable version: + +```terminal +dart --version +``` -### 1. Get the prerequisites +#### Node.js -Install the following tools, if you don't have them already: +The latest stable LTS release of Node.js is required to build the site. +If you don't have Node.js or need to update, download your +computer's corresponding version and follow the instructions +from the [Node.js download archive][]. +If you prefer, you can use a version manager such as [nvm][]. -- **bash**, the Bourne shell. - These instructions assume you're using `bash`, - and setup might not work if you use another shell. +If you already have Node installed, verify it's available on your path +and already the latest stable version _(`20` or later)_: -- **GNU Make**. - On Windows the easiest way to install Make is `choco install make` - using command prompt or powershell as an admin. - Other options include using a [subsystem][wsl]. +```terminal +node --version +``` -- **Docker**. - We use Docker for local dev, tests, and building the site. - Install it from https://docs.docker.com/get-docker/. +If your version is out of date, +follow the update instructions for how you originally installed it. -- **Firebase CLI**, for hosting the site locally. - One way to get this is to run `npm install -g firebase-tools`. - For full setup details, - read the [Firebase CLI documentation](https://firebase.google.com/docs/cli). +[Get the Dart SDK]: https://dart.dev/get-dart +[Node.js download archive]: https://nodejs.org/en/download/ +[nvm]: https://github.com/nvm-sh/nvm -### 2. Clone this repo _and_ its submodules +### Clone this repo and its submodules -> **Note:** This repo has git _submodules_, which affects how you clone it. -> The GitHub documentation has general help on [forking][] and [cloning][] repos. +> [!NOTE] +> This repository has git _submodules_, which affects how you clone it. +> The GitHub documentation has general help on +> [forking][] and [cloning][] repos. If you're not a member of the Dart organization, we recommend you **create a fork** of this repo under your own account, @@ -77,7 +99,7 @@ _choose one_ of the following submodule-cloning techniques: using the `--recurse-submodules` option: ```terminal - $ git clone --recurse-submodules https://github.com/dart-lang/site-www.git + git clone --recurse-submodules https://github.com/dart-lang/site-www.git ``` *OR* @@ -86,155 +108,164 @@ _choose one_ of the following submodule-cloning techniques: then run this command from the repo root: ```terminal - $ git submodule update --init --recursive + git submodule update --init --recursive ``` -> **Note:** At any time during development +> [!NOTE] +> At any time during development > you can use the `git submodule` command to refresh submodules: > > ```terminal -> $ git pull; git submodule update --init --recursive +> git pull && git submodule update --init --recursive > ``` -## Setting up your local environment and serve changes +## Set up your local environment and serve changes + +Before you continue setting up the site infrastructure, +verify the correct versions of Dart and Node.js are set up and available by +following the instructions in [Get the prerequisites](#get-the-prerequisites). 1. _Optional:_ After cloning the repo and its submodules, create a branch for your changes: ```terminal - $ git checkout -b + git checkout -b ``` -2. If the Docker Desktop application isn't already running on your machine, - start it. Look for the Docker status icon: if it has an exclamation - point (`!`), then update Docker Desktop before proceeding. +2. From the root directory of the repository, + fetch the site's Dart dependencies. -3. Run the initial local setup command: + ```terminal + dart pub get + ``` + +3. From the root directory of the repository, + enable [`corepack`][] to set up [`pnpm`][]. + `corepack` comes bundled with Node and `pnpm` + is an alternative, efficient package manager for npm packages. + If you already have `pnpm` installed or installed it a different way, + you can skip the `corepack` commands. ```terminal - $ make setup + corepack enable + corepack install ``` -4. Serve the site locally (via `docker-compose`): +4. Once you have `pnpm` installed and setup, + fetch the site's npm dependencies. + We recommend you use `pnpm`, but you can also use `npm`. ```terminal - $ make up + pnpm install ``` - The site is generated, and then the development server runs in the - Docker container, with the generated `_site` directory visible locally - as a mirrored volume from inside the container. +5. From the root directory, serve the site locally. -5. View your changes in the browser by navigating to `http://localhost:4000`. - > **Note:** Unless you're editing files under `site-shared`, - > you can safely ignore `ERROR: directory is already being watched` messages. - > For details, see [#1363](https://github.com/flutter/website/issues/1363). + ```terminal + dart run dart_site serve + ``` -6. Make your changes to the local repo. + This command generates and serves the site on a + local port that's printed to your terminal. - The site will rebuild and the browser will autoreload to reflect the changes. +6. View your changes in the browser by navigating to . - > **Tip:** If you aren't seeing the changes you expect (e.g. src/_data), - > Ctrl + C out of your running dev server and rebuild the site from scratch - > using the following commands: - > - > ```terminal - > $ make down && make clean && make up - > ``` + > [!NOTE] + > The port might be different if `4000` is taken. + + To instead view the source of generated site files, + check the `_site` directory. -7. Commit your changes to the branch and submit your PR. - > See [Pre-push site checks](#pre-push-site-checks) +7. Make your changes to the local repo. -8. When you've finished developing, shut down the Docker container: + The site should automatically rebuild on most changes, but if + something doesn't update, exit the process and rerun the command. + Improvements to this functionality are planned. + Please open a new issue to track the issue if this occurs. - ```terminal - $ make down - ``` +8. Commit your changes to the branch and submit your PR. -> **Tip:** To find additional commands, read the [Makefile][]. -> For example, if you need to debug the Docker setup, -> you can run: -> -> ```terminal -> $ make run -> ``` + If your change is large, or you'd like to test it, + consider [validating your changes](#validate-your-changes). -## Pre-push site checks +> [!TIP] +> To find additional commands that you can run, +> run `dart run dart_site --help` from the repository's root directory. -### Checking documentation and example code +[`corepack`]: https://nodejs.org/api/corepack.html +[`pnpm`]: https://pnpm.io/ -If you've made changes to this site's documentation and/or example code, -and committed locally, then run the following commands before pushing your work: +## Validate your changes -```terminal -# Enter a running Docker container shell -$ make run +### Check documentation and example code + +If you've made changes to the code in the `/examples` or `/tool` directories, +commit your work, then run the following command to +verify it is up to date and matches the site standards. -# Check/validate example code -$ dart run dart_site check-all +```terminal +dart run dart_site check-all ``` -If these scripts report errors or warnings, -then address those issues and rerun the above commands. -Otherwise, you can push your changes. +If this script reports any errors or warnings, +then address those issues and rerun the command. +If you have any issues, leave a comment on your issue or pull request, +and we'll try our best to help you. +You can also chat with us on the `#hackers-devrel` channel +on the [Flutter contributors Discord][]! + +[Flutter contributors Discord]: https://github.com/flutter/flutter/wiki/Chat -## Deploying to a staging site +## [Optional] Deploy to a staging site -You can deploy your local edits to a -personal Firebase hosting staging site as follows: +Submitted pull requests can be automatically staged +by a site maintainer. +If you'd like to stage the site yourself though, +you can build a full version and upload it to Firebase. 1. If you don't already have a Firebase project, - Navigate to the [Firebase Console](https://console.firebase.google.com) and create your own Firebase project (for example, `dart-dev-staging`). - - Head back to your local repo shell and verify that you are logged in. + - Head back to your local terminal and verify that you are logged in. ```terminal - $ firebase login + firebase login ``` - Ensure that your project exists and activate that project: ```terminal - $ firebase projects:list - $ firebase use + firebase projects:list + firebase use ``` -1. Build the site via Docker: +2. From the root directory of the repository, build the site: ```terminal - $ make build + dart run dart_site build ``` This will build the site and copy it to your local `_site` directory. If that directory previously existed, it will be replaced. -1. Deploy to your activated Firebase project's default hosting site: +3. Deploy to your activated Firebase project's default hosting site: ```terminal - $ FIREBASE_PROJECT= make deploy + firebase deploy --only hosting ``` - > **TIP:** Add your `FIREBASE_PROJECT` env var to your `.env` file - > and it will overwrite the default every time you deploy without specifying. - -1. Navigate to your PR on GitHub and update it with the location of - the staged version, the names of your reviewers, and so on. +4. Navigate to your PR on GitHub and include the link of the staged version. + Do consider adding a reference to the commit you staged, + so that reviewers know if any further changes have been made. [Build Status SVG]: https://github.com/dart-lang/site-www/workflows/build/badge.svg [OpenSSF Scorecard SVG]: https://api.securityscorecards.dev/projects/github.com/dart-lang/site-www/badge [Scorecard Results]: https://deps.dev/project/github/dart-lang%2Fsite-www -[cloning]: https://help.github.com/articles/cloning-a-repository -[DartPad]: https://dartpad.dev +[cloning]: https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository +[Eleventy]: https://www.11ty.dev/ [Firebase]: https://firebase.google.com/ -[first-timers SVG]: https://img.shields.io/badge/first--timers--only-friendly-blue.svg?style=flat-square -[first-timers]: https://www.firsttimersonly.com/ -[forking]: https://docs.github.com/en/get-started/quickstart/fork-a-repo -[Jekyll]: https://jekyllrb.com -[Makefile]: (https://github.com/dart-lang/site-www/blob/main/Makefile) +[forking]: https://docs.github.com/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo [Repo on GitHub Actions]: https://github.com/dart-lang/site-www/actions?query=workflow%3Abuild+branch%3Amain -[site-www]: https://github.com/dart-lang/site-www -[Troubleshooting wiki page]: https://github.com/dart-lang/site-www/wiki/Troubleshooting -[wsl]: https://docs.microsoft.com/en-us/windows/wsl/install diff --git a/_config.yml b/_config.yml deleted file mode 100644 index 75a393ffc6..0000000000 --- a/_config.yml +++ /dev/null @@ -1,99 +0,0 @@ -# Site settings -title: Dart -description: >- - Dart is a client-optimized language for developing fast apps on any platform. -url: https://dart.dev -repo: - this: https://github.com/dart-lang/site-www - shared: https://github.com/dart-lang/site-shared -branch: main -port: 4000 -source: src - -strict_front_matter: true -liquid: - error_mode: strict - strict_filters: true -future: true # In support of https://github.com/dart-lang/site-www/issues/1111 -sass: - sass_dir: _sass - style: compressed - load_paths: - - ../node_modules/bootstrap-scss -plugins: - - jekyll-toc -toc: - min_level: 2 - max_level: 3 - no_toc_section_class: no_toc_section - - -flutter: https://flutter.dev -flutter-docs: https://docs.flutter.dev -dart-api: https://api.dart.dev -flutter-api: https://api.flutter.dev -pub: https://pub.dev -pub-api: https://pub.dev/documentation -pub-pkg: https://pub.dev/packages -dartpad: https://dartpad.dev -news: https://news.dartlang.org -announce: https://groups.google.com/a/dartlang.org/g/announce -gh: https://github.com -gh-dart: - org: https://github.com/dart-lang - sdk: https://github.com/dart-lang/sdk - lang: https://github.com/dart-lang/language - site: https://github.com/dart-lang/site-www - -show_banner: true - -defaults: -- scope: - path: '' - # type: pages - values: - layout: default - toc: true - -# Increment this global og:image URL version number (used as a query parameter) -# when you update any og:image file. (Also increment the corresponding number -# in the `firebase.json` redirect rule.) -og_image_vers: "?2" - - -## Site-wide shorthands - -alert: - important: >- -