base on The source for the Dart website. # <img src="https://github.com/dart-lang/site-shared/blob/main/src/_assets/image/dart/logo/64.png" alt="Dart" width="28" height="28"/> The Dart language site (dart.dev) [![Build Status SVG][]][Repo on GitHub Actions] [![OpenSSF Scorecard SVG][]][Scorecard Results] <a href="https://studio.firebase.google.com/import?url=https%3A%2F%2Fgithub.com%2Fdart-lang%2Fsite-www"> <img height="32" alt="Open in Firebase Studio" src="https://cdn.firebasestudio.dev/btn/open_blue_32.svg"> </a> The documentation site for the [Dart programming language](https://dart.dev), built with [Jaspr][] and hosted on [Firebase][]. 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. 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 small, contained 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. If your change involves code samples, adds/removes pages, or affects navigation, do consider building and testing your work before submitting. If you want or need to build the site, follow the steps below. ## Build the site For changes beyond simple text and CSS tweaks, 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 ``` ### Clone this repo If you're not a member of the Dart organization, we recommend you [create a fork][] of this repo under your own account, and then submit a PR from that fork. Once you have a fork (or you're a Dart org member), clone the repository with `git clone`: ```bash git clone https://github.com/dart-lang/site-www.git ``` [create a fork]: https://docs.github.com/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo ## Set up your local environment and serve changes Before you continue setting up the site infrastructure, verify the correct version of Dart is set up and available by following the instructions in [Get the prerequisites](#get-the-prerequisites). 1. _Optional:_ After cloning the repo, create a branch for your changes: ```terminal git checkout -b <BRANCH_NAME> ``` 2. From the root directory of the repository, fetch the site's Dart dependencies. ```terminal dart pub get ``` 3. From the root directory, run the `dash_site` tool to validate your setup and learn about the available commands. ```terminal dart run dash_site --help ``` 4. From the root directory, serve the site locally. ```terminal dart run dash_site serve ``` This command generates and serves the site on a local port that's printed to your terminal. 5. View your changes in the browser by navigating to <http://localhost:8080>. Note the port might be different if `8080` is taken. 6. Make your changes to the local repo. 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. 9. Commit your changes to the branch and submit your PR. If your change is large, or you'd like to test it, consider [validating your changes](#validate-your-changes). > [!TIP] > To find additional commands that you can run, > run `dart run dash_site --help` from the repository's root directory. ## Validate your changes ### 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. ```terminal dart run dash_site check-all ``` 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 ### Refresh code excerpts A build that fails with the error `Error: Some code excerpts needed to be updated!` means that one or more code excerpts in the site Markdown files aren't identical to the code regions declared in the corresponding `.dart` files. To resolve this error, from the root of the `site-www` directory, run `dart run dash_site refresh-excerpts`. To learn more about creating, editing, and using code excerpts, check out the [excerpt updater package documentation][]. [excerpt updater package documentation]: https://github.com/dart-lang/site-shared/tree/main/pkgs/excerpter#readme [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 [Jaspr]: https://jaspr.site [Firebase]: https://firebase.google.com/ [Repo on GitHub Actions]: https://github.com/dart-lang/site-www/actions?query=workflow%3Abuild+branch%3Amain ", Assign "at most 3 tags" to the expected json: {"id":"9671","tags":[]} "only from the tags list I provide: []" returns me the "expected json"