diff --git a/src/_includes/head.html b/src/_includes/head.html index 472e8ae2fe..189023111b 100644 --- a/src/_includes/head.html +++ b/src/_includes/head.html @@ -97,5 +97,5 @@ {% endfor -%} {% endif -%} - {% include 'analytics.html' -%} + {% render 'analytics.html' -%} diff --git a/src/_includes/page-header.html b/src/_includes/page-header.html index e655644fbe..4f218d69a0 100644 --- a/src/_includes/page-header.html +++ b/src/_includes/page-header.html @@ -10,4 +10,4 @@

{% endif -%} {% endif -%} -{% if site.show_banner -%} {% include 'banner.html' %} {%- endif -%} +{% if site.show_banner -%} {% render 'banner.html' %} {%- endif -%} diff --git a/src/_layouts/default.html b/src/_layouts/default.html index 2141331d39..76244b72d3 100644 --- a/src/_layouts/default.html +++ b/src/_layouts/default.html @@ -8,8 +8,8 @@ {% endif -%} {% endif -%} - {% include 'cookie-notice.html' %} - {% include 'gtags.html' %} + {% render 'cookie-notice.html' %} + {% render 'gtags.html' %} {% include 'page-header.html', obsolete:obsolete %} {% include 'navigation-side.html' %}
@@ -38,6 +38,6 @@

{{title }}

- {% include 'page-footer.html' %} + {% render 'page-footer.html' %} diff --git a/src/_layouts/error.html b/src/_layouts/error.html index 846c1e5860..4f1a6a1e0c 100644 --- a/src/_layouts/error.html +++ b/src/_layouts/error.html @@ -2,8 +2,8 @@ {% include 'head.html' %} - {% include 'cookie-notice.html' %} - {% include 'gtags.html' %} + {% render 'cookie-notice.html' %} + {% render 'gtags.html' %} {% include 'page-header.html' %} {% include 'navigation-side.html' %}
@@ -11,6 +11,6 @@ {{content}}
- {% include 'page-footer.html' %} + {% render 'page-footer.html' %} diff --git a/src/_layouts/homepage.html b/src/_layouts/homepage.html index cfee25d1d5..d04834395f 100644 --- a/src/_layouts/homepage.html +++ b/src/_layouts/homepage.html @@ -2,13 +2,13 @@ {% include 'head.html' %} - {% include 'cookie-notice.html' %} - {% include 'gtags.html' %} + {% render 'cookie-notice.html' %} + {% render 'gtags.html' %} {% include 'page-header.html' %} {% include 'navigation-side.html' %}
{{content}}
- {% include 'page-footer.html' %} + {% render 'page-footer.html' %} diff --git a/src/content/codelabs/async-await.md b/src/content/codelabs/async-await.md index 9bd3534d91..777a665632 100644 --- a/src/content/codelabs/async-await.md +++ b/src/content/codelabs/async-await.md @@ -28,7 +28,7 @@ Estimated time to complete this codelab: 40-60 minutes. :::note This page uses embedded DartPads to display examples and exercises. -{% include 'dartpads-embedded-troubleshooting.md' %} +{% render 'dartpads-embedded-troubleshooting.md' %} ::: The exercises in this codelab have partially completed code snippets. diff --git a/src/content/codelabs/dart-cheatsheet.md b/src/content/codelabs/dart-cheatsheet.md index 43e2da68c1..e762ddd814 100644 --- a/src/content/codelabs/dart-cheatsheet.md +++ b/src/content/codelabs/dart-cheatsheet.md @@ -22,7 +22,7 @@ for an explanation and the answer. :::note This page uses embedded DartPads to display runnable examples. -{% include 'dartpads-embedded-troubleshooting.md' %} +{% render 'dartpads-embedded-troubleshooting.md' %} ::: ## String interpolation diff --git a/src/content/codelabs/iterables.md b/src/content/codelabs/iterables.md index 8d9a062ef8..38ce720983 100644 --- a/src/content/codelabs/iterables.md +++ b/src/content/codelabs/iterables.md @@ -33,7 +33,7 @@ Estimated time to complete this codelab: 60 minutes. :::note This page uses embedded DartPads to display examples and exercises. -{% include 'dartpads-embedded-troubleshooting.md' %} +{% render 'dartpads-embedded-troubleshooting.md' %} ::: The exercises in this codelab have partially completed code snippets. diff --git a/src/content/effective-dart/design.md b/src/content/effective-dart/design.md index 35dfdb94f0..47f6c6ca31 100644 --- a/src/content/effective-dart/design.md +++ b/src/content/effective-dart/design.md @@ -340,7 +340,7 @@ previous guidelines state, either: ### PREFER naming a method `to___()` if it copies the object's state to a new object -{% include 'linter-rule-mention.md', rules:'use_to_and_as_if_applicable' %} +{% render 'linter-rule-mention.md', rules:'use_to_and_as_if_applicable' %} A *conversion* method is one that returns a new object containing a copy of almost all of the state of the receiver but usually in some different form or @@ -358,7 +358,7 @@ dateTime.toLocal(); ### PREFER naming a method `as___()` if it returns a different representation backed by the original object -{% include 'linter-rule-mention.md', rules:'use_to_and_as_if_applicable' %} +{% render 'linter-rule-mention.md', rules:'use_to_and_as_if_applicable' %} Conversion methods are "snapshots". The resulting object has its own copy of the original object's state. There are other conversion-like methods that return @@ -520,7 +520,7 @@ you can in a procedural or functional language. ### AVOID defining a one-member abstract class when a simple function will do -{% include 'linter-rule-mention.md', rules:'one_member_abstracts' %} +{% render 'linter-rule-mention.md', rules:'one_member_abstracts' %} Unlike Java, Dart has first-class functions, closures, and a nice light syntax for using them. If all you need is something like a callback, just use a @@ -543,7 +543,7 @@ abstract class Predicate { ### AVOID defining a class that contains only static members -{% include 'linter-rule-mention.md', rules:'avoid_classes_with_only_static_members' %} +{% render 'linter-rule-mention.md', rules:'avoid_classes_with_only_static_members' %} In Java and C#, every definition *must* be inside a class, so it's common to see "classes" that exist only as a place to stuff static members. Other classes are @@ -656,7 +656,7 @@ comment. ### PREFER defining a pure `mixin` or pure `class` to a `mixin class` -{% include 'linter-rule-mention.md', rules:'prefer_mixin' %} +{% render 'linter-rule-mention.md', rules:'prefer_mixin' %} Dart previously (language version [2.12](/guides/language/evolution#dart-2-12) to [2.19](/guides/language/evolution#dart-2-19)) allowed any class that @@ -708,7 +708,7 @@ A member belongs to an object and can be either methods or instance variables. ### PREFER making fields and top-level variables `final` -{% include 'linter-rule-mention.md', rules:'prefer_final_fields' %} +{% render 'linter-rule-mention.md', rules:'prefer_final_fields' %} State that is not *mutable*—that does not change over time—is easier for programmers to reason about. Classes and libraries that minimize the @@ -821,7 +821,7 @@ dataSet.minimumValue; ### DO use setters for operations that conceptually change properties -{% include 'linter-rule-mention.md', rules:'use_setters_to_change_properties' %} +{% render 'linter-rule-mention.md', rules:'use_setters_to_change_properties' %} Deciding between a setter versus a method is similar to deciding between a getter versus a method. In both cases, the operation should be "field-like". @@ -847,7 +847,7 @@ button.visible = false; ### DON'T define a setter without a corresponding getter -{% include 'linter-rule-mention.md', rules:'avoid_setters_without_getters' %} +{% render 'linter-rule-mention.md', rules:'avoid_setters_without_getters' %} Users think of getters and setters as visible properties of an object. A "dropbox" property that can be written to but not seen is confusing and @@ -925,7 +925,7 @@ empty container, it might make sense to use a nullable type. ### AVOID returning `this` from methods just to enable a fluent interface -{% include 'linter-rule-mention.md', rules:'avoid_returning_this' %} +{% render 'linter-rule-mention.md', rules:'avoid_returning_this' %} Method cascades are a better solution for chaining method calls. @@ -1049,7 +1049,7 @@ various cases, but the rough summary is: ### DO type annotate variables without initializers -{% include 'linter-rule-mention.md', rules:'prefer_typing_uninitialized_variables' %} +{% render 'linter-rule-mention.md', rules:'prefer_typing_uninitialized_variables' %} The type of a variable—top-level, local, static field, or instance field—can often be inferred from its initializer. However, if there is no @@ -1078,7 +1078,7 @@ if (node is Constructor) { ### DO type annotate fields and top-level variables if the type isn't obvious -{% include 'linter-rule-mention.md', rules:'type_annotate_public_apis' %} +{% render 'linter-rule-mention.md', rules:'type_annotate_public_apis' %} Type annotations are important documentation for how a library should be used. They form boundaries between regions of a program to isolate the source of a @@ -1130,7 +1130,7 @@ annotations on APIs help *users* of your code, types on private members help ### DON'T redundantly type annotate initialized local variables -{% include 'linter-rule-mention.md', rules:'omit_local_variable_types' %} +{% render 'linter-rule-mention.md', rules:'omit_local_variable_types' %} Local variables, especially in modern code where functions tend to be small, have very little scope. Omitting the type focuses the reader's attention on the @@ -1237,7 +1237,7 @@ different type annotation conventions, as described in the next two guidelines. ### DON'T annotate inferred parameter types on function expressions -{% include 'linter-rule-mention.md', rules:'avoid_types_on_closure_parameters' %} +{% render 'linter-rule-mention.md', rules:'avoid_types_on_closure_parameters' %} Anonymous functions are almost always immediately passed to a method taking a callback of some type. @@ -1268,7 +1268,7 @@ function's parameters. In those cases, you may need to annotate. ### DON'T type annotate initializing formals -{% include 'linter-rule-mention.md', rules:'type_init_formals' %} +{% render 'linter-rule-mention.md', rules:'type_init_formals' %} If a constructor parameter is using `this.` to initialize a field, or `super.` to forward a super parameter, @@ -1511,7 +1511,7 @@ void handleError([!void Function()!] operation, [!Function!] errorHandler) { ### DON'T specify a return type for a setter -{% include 'linter-rule-mention.md', rules:'avoid_return_types_on_setters' %} +{% render 'linter-rule-mention.md', rules:'avoid_return_types_on_setters' %} Setters always return `void` in Dart. Writing the word is pointless. @@ -1528,7 +1528,7 @@ set foo(Foo value) { ... } ### DON'T use the legacy typedef syntax -{% include 'linter-rule-mention.md', rules:'prefer_generic_function_type_aliases' %} +{% render 'linter-rule-mention.md', rules:'prefer_generic_function_type_aliases' %} Dart has two notations for defining a named typedef for a function type. The original syntax looks like: @@ -1586,7 +1586,7 @@ it's deprecated. ### PREFER inline function types over typedefs -{% include 'linter-rule-mention.md', rules:'avoid_private_typedef_functions' %} +{% render 'linter-rule-mention.md', rules:'avoid_private_typedef_functions' %} In Dart, if you want to use a function type for a field, variable, or generic type argument, you can define a typedef for the function type. @@ -1623,7 +1623,7 @@ that clarity. ### PREFER using function type syntax for parameters -{% include 'linter-rule-mention.md', rules:'use_function_type_syntax_for_parameters' %} +{% render 'linter-rule-mention.md', rules:'use_function_type_syntax_for_parameters' %} Dart has a special syntax when defining a parameter whose type is a function. Sort of like in C, you surround the parameter's name with the function's return @@ -1758,7 +1758,7 @@ In Dart, optional parameters can be either positional or named, but not both. ### AVOID positional boolean parameters -{% include 'linter-rule-mention.md', rules:'avoid_positional_boolean_parameters' %} +{% render 'linter-rule-mention.md', rules:'avoid_positional_boolean_parameters' %} Unlike other types, booleans are usually used in literal form. Values like numbers are usually wrapped in named constants, but we typically pass around @@ -1872,7 +1872,7 @@ elements to follow. ### DO override `hashCode` if you override `==` -{% include 'linter-rule-mention.md', rules:'hash_and_equals' %} +{% render 'linter-rule-mention.md', rules:'hash_and_equals' %} The default hash code implementation provides an *identity* hash—two objects generally only have the same hash code if they are the exact same @@ -1900,7 +1900,7 @@ you're trying to express. ### AVOID defining custom equality for mutable classes -{% include 'linter-rule-mention.md', rules:'avoid_equals_and_hash_code_on_mutable_classes' %} +{% render 'linter-rule-mention.md', rules:'avoid_equals_and_hash_code_on_mutable_classes' %} When you define `==`, you also have to define `hashCode`. Both of those should take into account the object's fields. If those fields *change* then that @@ -1912,7 +1912,7 @@ true. ### DON'T make the parameter to `==` nullable -{% include 'linter-rule-mention.md', rules:'avoid_null_checks_in_equality_operators' %} +{% render 'linter-rule-mention.md', rules:'avoid_null_checks_in_equality_operators' %} The language specifies that `null` is equal only to itself, and that the `==` method is called only if the right-hand side is not `null`. diff --git a/src/content/effective-dart/documentation.md b/src/content/effective-dart/documentation.md index 39619b5cd6..08fcdb8c5f 100644 --- a/src/content/effective-dart/documentation.md +++ b/src/content/effective-dart/documentation.md @@ -72,7 +72,7 @@ and uses the special `///` syntax that `dart doc` looks for. ### DO use `///` doc comments to document members and types -{% include 'linter-rule-mention.md', rules:'slash_for_doc_comments' %} +{% render 'linter-rule-mention.md', rules:'slash_for_doc_comments' %} Using a doc comment instead of a regular comment enables [`dart doc`][] to find it @@ -101,7 +101,7 @@ up. ### PREFER writing doc comments for public APIs -{% include 'linter-rule-mention.md', rules:'package_api_docs, public_member_api_docs' %} +{% render 'linter-rule-mention.md', rules:'package_api_docs, public_member_api_docs' %} You don't have to document every single library, top-level variable, type, and member, but you should document most of them. @@ -342,7 +342,7 @@ makes an API easier to learn. ### DO use square brackets in doc comments to refer to in-scope identifiers -{% include 'linter-rule-mention.md', rules:'comment_references' %} +{% render 'linter-rule-mention.md', rules:'comment_references' %} If you surround things like variable, method, or type names in square brackets, then `dart doc` looks up the name and links to the relevant API docs. diff --git a/src/content/effective-dart/index.md b/src/content/effective-dart/index.md index 99a174f7d7..1f3e130f7e 100644 --- a/src/content/effective-dart/index.md +++ b/src/content/effective-dart/index.md @@ -105,7 +105,7 @@ that can help you follow a guideline then the guideline links to those rules. The links use the following format: -{% include 'linter-rule-mention.md', rules:'unnecessary_getters_setters' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_getters_setters' %} To learn how to use the linter, see [Enabling linter rules][] diff --git a/src/content/effective-dart/style.md b/src/content/effective-dart/style.md index 0c0e9fdbcd..bf32e30bf5 100644 --- a/src/content/effective-dart/style.md +++ b/src/content/effective-dart/style.md @@ -35,7 +35,7 @@ Identifiers come in three flavors in Dart. ### DO name types using `UpperCamelCase` -{% include 'linter-rule-mention.md', rules:'camel_case_types' %} +{% render 'linter-rule-mention.md', rules:'camel_case_types' %} Classes, enum types, typedefs, and type parameters should capitalize the first letter of each word (including the first word), and use no separators. @@ -77,7 +77,7 @@ class C { ... } ### DO name extensions using `UpperCamelCase` -{% include 'linter-rule-mention.md', rules:'camel_case_extensions' %} +{% render 'linter-rule-mention.md', rules:'camel_case_extensions' %} Like types, [extensions][] should capitalize the first letter of each word (including the first word), @@ -95,7 +95,7 @@ extension SmartIterable on Iterable { ... } ### DO name packages, directories, and source files using `lowercase_with_underscores` {:#do-name-packages-and-file-system-entities-using-lowercase-with-underscores} -{% include 'linter-rule-mention.md', rules:'file_names, package_names' %} +{% render 'linter-rule-mention.md', rules:'file_names, package_names' %} Some file systems are not case-sensitive, so many projects require filenames to be all lowercase. Using a separating character allows names to still be readable @@ -120,7 +120,7 @@ mypackage ### DO name import prefixes using `lowercase_with_underscores` -{% include 'linter-rule-mention.md', rules:'library_prefixes' %} +{% render 'linter-rule-mention.md', rules:'library_prefixes' %} ```dart tag=good @@ -139,7 +139,7 @@ import 'package:js/js.dart' as JS; ### DO name other identifiers using `lowerCamelCase` -{% include 'linter-rule-mention.md', rules:'non_constant_identifier_names' %} +{% render 'linter-rule-mention.md', rules:'non_constant_identifier_names' %} Class members, top-level definitions, variables, parameters, and named parameters should capitalize the first letter of each word *except* the first @@ -159,7 +159,7 @@ void align(bool clearItems) { ### PREFER using `lowerCamelCase` for constant names -{% include 'linter-rule-mention.md', rules:'constant_identifier_names' %} +{% render 'linter-rule-mention.md', rules:'constant_identifier_names' %} In new code, use `lowerCamelCase` for constant variables, including enum values. @@ -330,7 +330,7 @@ A single linter rule handles all the ordering guidelines: ### DO place `dart:` imports before other imports -{% include 'linter-rule-mention.md', rules:'directives_ordering' %} +{% render 'linter-rule-mention.md', rules:'directives_ordering' %} ```dart tag=good @@ -344,7 +344,7 @@ import 'package:foo/foo.dart'; ### DO place `package:` imports before relative imports -{% include 'linter-rule-mention.md', rules:'directives_ordering' %} +{% render 'linter-rule-mention.md', rules:'directives_ordering' %} ```dart tag=good @@ -357,7 +357,7 @@ import 'util.dart'; ### DO specify exports in a separate section after all imports -{% include 'linter-rule-mention.md', rules:'directives_ordering' %} +{% render 'linter-rule-mention.md', rules:'directives_ordering' %} ```dart tag=good @@ -377,7 +377,7 @@ import 'src/foo_bar.dart'; ### DO sort sections alphabetically -{% include 'linter-rule-mention.md', rules:'directives_ordering' %} +{% render 'linter-rule-mention.md', rules:'directives_ordering' %} ```dart tag=good @@ -436,7 +436,7 @@ to produce beautiful code. ### AVOID lines longer than 80 characters -{% include 'linter-rule-mention.md', rules:'lines_longer_than_80_chars' %} +{% render 'linter-rule-mention.md', rules:'lines_longer_than_80_chars' %} Readability studies show that long lines of text are harder to read because your eye has to travel farther when moving to the beginning of the next line. This is @@ -463,7 +463,7 @@ shorter ones can alter the program. ### DO use curly braces for all flow control statements -{% include 'linter-rule-mention.md', rules:'curly_braces_in_flow_control_structures' %} +{% render 'linter-rule-mention.md', rules:'curly_braces_in_flow_control_structures' %} Doing so avoids the [dangling else][] problem. diff --git a/src/content/effective-dart/usage.md b/src/content/effective-dart/usage.md index 228a1e6651..65a8a72e98 100644 --- a/src/content/effective-dart/usage.md +++ b/src/content/effective-dart/usage.md @@ -24,7 +24,7 @@ to cover `import` and `export` directives. The guidelines apply equally to both. ### DO use strings in `part of` directives -{% include 'linter-rule-mention.md', rules:'use_string_in_part_of_directives' %} +{% render 'linter-rule-mention.md', rules:'use_string_in_part_of_directives' %} Many Dart developers avoid using `part` entirely. They find it easier to reason about their code when each library is a single file. If you do choose to use @@ -65,7 +65,7 @@ part of my_library; ### DON'T import libraries that are inside the `src` directory of another package -{% include 'linter-rule-mention.md', rules:'implementation_imports' %} +{% render 'linter-rule-mention.md', rules:'implementation_imports' %} The `src` directory under `lib` [is specified][package guide] to contain libraries private to the package's own implementation. The way package @@ -81,7 +81,7 @@ theoretically non-breaking point release of that package could break your code. ### DON'T allow an import path to reach into or out of `lib` -{% include 'linter-rule-mention.md', rules:'avoid_relative_lib_imports' %} +{% render 'linter-rule-mention.md', rules:'avoid_relative_lib_imports' %} A `package:` import lets you access a library inside a package's `lib` directory @@ -132,7 +132,7 @@ import libraries from other places in the package. ### PREFER relative import paths -{% include 'linter-rule-mention.md', rules:'prefer_relative_imports' %} +{% render 'linter-rule-mention.md', rules:'prefer_relative_imports' %} Whenever the previous rule doesn't come into play, follow this one. When an import does *not* reach across `lib`, prefer using relative imports. @@ -175,7 +175,7 @@ import 'test_utils.dart'; // Relative within 'test' is fine. ### DON'T explicitly initialize variables to `null` -{% include 'linter-rule-mention.md', rules:'avoid_init_to_null' %} +{% render 'linter-rule-mention.md', rules:'avoid_init_to_null' %} If a variable has a non-nullable type, Dart reports a compile error if you try to use it before it has been definitely initialized. If the variable is @@ -216,7 +216,7 @@ Item? bestDeal(List cart) { ### DON'T use an explicit default value of `null` -{% include 'linter-rule-mention.md', rules:'avoid_init_to_null' %} +{% render 'linter-rule-mention.md', rules:'avoid_init_to_null' %} If you make a nullable parameter optional but don't give it a default value, the language implicitly uses `null` as the default, so there's no need to write it. @@ -428,7 +428,7 @@ Here are some best practices to keep in mind when composing strings in Dart. ### DO use adjacent strings to concatenate string literals -{% include 'linter-rule-mention.md', rules:'prefer_adjacent_string_concatenation' %} +{% render 'linter-rule-mention.md', rules:'prefer_adjacent_string_concatenation' %} If you have two string literals—not values, but the actual quoted literal form—you do not need to use `+` to concatenate them. Just like in C and @@ -449,7 +449,7 @@ raiseAlarm('ERROR: Parts of the spaceship are on fire. Other ' + ### PREFER using interpolation to compose strings and values -{% include 'linter-rule-mention.md', rules:'prefer_interpolation_to_compose_strings' %} +{% render 'linter-rule-mention.md', rules:'prefer_interpolation_to_compose_strings' %} If you're coming from other languages, you're used to using long chains of `+` to build a string out of literals and other values. That does work in Dart, but @@ -470,7 +470,7 @@ It's fine to use `.toString()` when converting only a single object to a string. ### AVOID using curly braces in interpolation when not needed -{% include 'linter-rule-mention.md', rules:'unnecessary_brace_in_string_interps' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_brace_in_string_interps' %} If you're interpolating a simple identifier not immediately followed by more alphanumeric text, the `{}` should be omitted. @@ -492,7 +492,7 @@ The following best practices apply to collections. ### DO use collection literals when possible -{% include 'linter-rule-mention.md', rules:'prefer_collection_literals' %} +{% render 'linter-rule-mention.md', rules:'prefer_collection_literals' %} Dart has three core collection types: List, Map, and Set. The Map and Set classes have unnamed constructors like most classes do. But because these @@ -551,7 +551,7 @@ arguments.addAll(filePaths ### DON'T use `.length` to see if a collection is empty -{% include 'linter-rule-mention.md', rules:'prefer_is_empty, prefer_is_not_empty' %} +{% render 'linter-rule-mention.md', rules:'prefer_is_empty, prefer_is_not_empty' %} The [Iterable][] contract does not require that a collection know its length or be able to provide it in constant time. Calling `.length` just to see if the @@ -577,7 +577,7 @@ if (!words.isEmpty) return words.join(' '); ### AVOID using `Iterable.forEach()` with a function literal -{% include 'linter-rule-mention.md', rules:'avoid_function_literals_in_foreach_calls' %} +{% render 'linter-rule-mention.md', rules:'avoid_function_literals_in_foreach_calls' %} `forEach()` functions are widely used in JavaScript because the built in `for-in` loop doesn't do what you usually want. In Dart, if you want to iterate @@ -656,7 +656,7 @@ you don't care about the type, then use `toList()`. ### DO use `whereType()` to filter a collection by type -{% include 'linter-rule-mention.md', rules:'prefer_iterable_whereType' %} +{% render 'linter-rule-mention.md', rules:'prefer_iterable_whereType' %} Let's say you have a list containing a mixture of objects, and you want to get just the integers out of it. You could use `where()` like this: @@ -837,7 +837,7 @@ involving functions. ### DO use a function declaration to bind a function to a name -{% include 'linter-rule-mention.md', rules:'prefer_function_declarations_over_variables' %} +{% render 'linter-rule-mention.md', rules:'prefer_function_declarations_over_variables' %} Modern languages have realized how useful local nested functions and closures are. It's common to have a function defined inside another one. In many cases, @@ -867,7 +867,7 @@ void main() { ### DON'T create a lambda when a tear-off will do -{% include 'linter-rule-mention.md', rules:'unnecessary_lambdas' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_lambdas' %} When you refer to a function, method, or named constructor but omit the parentheses, Dart creates a _tear-off_—a closure that takes the same @@ -1029,7 +1029,7 @@ variables). The following best practices apply to an object's members. ### DON'T wrap a field in a getter and setter unnecessarily -{% include 'linter-rule-mention.md', rules:'unnecessary_getters_setters' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_getters_setters' %} In Java and C#, it's common to hide all fields behind getters and setters (or properties in C#), even if the implementation just forwards to the field. That @@ -1088,7 +1088,7 @@ don't reach for that until you need to. ### CONSIDER using `=>` for simple members -{% include 'linter-rule-mention.md', rules:'prefer_expression_function_bodies' %} +{% render 'linter-rule-mention.md', rules:'prefer_expression_function_bodies' %} In addition to using `=>` for function expressions, Dart also lets you define members with it. That style is a good fit for simple members that just calculate @@ -1139,7 +1139,7 @@ set x(num value) => center = Point(value, center.y); ### DON'T use `this.` except to redirect to a named constructor or to avoid shadowing {:#dont-use-this-when-not-needed-to-avoid-shadowing} -{% include 'linter-rule-mention.md', rules:'unnecessary_this' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_this' %} JavaScript requires an explicit `this.` to refer to members on the object whose method is currently being executed, but Dart—like C++, Java, and @@ -1270,7 +1270,7 @@ The following best practices apply to declaring constructors for a class. ### DO use initializing formals when possible -{% include 'linter-rule-mention.md', rules:'prefer_initializing_formals' %} +{% render 'linter-rule-mention.md', rules:'prefer_initializing_formals' %} Many fields are initialized directly from a constructor parameter, like: @@ -1342,7 +1342,7 @@ performance. ### DO use `;` instead of `{}` for empty constructor bodies -{% include 'linter-rule-mention.md', rules:'empty_constructor_bodies' %} +{% render 'linter-rule-mention.md', rules:'empty_constructor_bodies' %} In Dart, a constructor with an empty body can be terminated with just a semicolon. (In fact, it's required for const constructors.) @@ -1365,7 +1365,7 @@ class Point { ### DON'T use `new` -{% include 'linter-rule-mention.md', rules:'unnecessary_new' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_new' %} The `new` keyword is optional when calling a constructor. Its meaning is not clear because factory constructors mean a @@ -1405,7 +1405,7 @@ Widget build(BuildContext context) { ### DON'T use `const` redundantly -{% include 'linter-rule-mention.md', rules:'unnecessary_const' %} +{% render 'linter-rule-mention.md', rules:'unnecessary_const' %} In contexts where an expression *must* be constant, the `const` keyword is implicit, doesn't need to be written, and shouldn't. Those contexts are any @@ -1449,7 +1449,7 @@ best practices apply to catching and throwing exceptions. ### AVOID catches without `on` clauses -{% include 'linter-rule-mention.md', rules:'avoid_catches_without_on_clauses' %} +{% render 'linter-rule-mention.md', rules:'avoid_catches_without_on_clauses' %} A catch clause with no `on` qualifier catches *anything* thrown by the code in the try block. [Pokémon exception handling][pokemon] is very likely not what you @@ -1492,7 +1492,7 @@ one of the core Exception classes or some other type. ### DON'T explicitly catch `Error` or types that implement it -{% include 'linter-rule-mention.md', rules:'avoid_catching_errors' %} +{% render 'linter-rule-mention.md', rules:'avoid_catching_errors' %} This follows from the above. Since an Error indicates a bug in your code, it should unwind the entire callstack, halt the program, and print a stack trace so @@ -1505,7 +1505,7 @@ and fix the code that is causing it to be thrown in the first place. ### DO use `rethrow` to rethrow a caught exception -{% include 'linter-rule-mention.md', rules:'use_rethrow_when_possible' %} +{% render 'linter-rule-mention.md', rules:'use_rethrow_when_possible' %} If you decide to rethrow an exception, prefer using the `rethrow` statement instead of throwing the same exception object using `throw`. diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index ca137a532b..62839b98a1 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -202,7 +202,7 @@ the pub package manager. The `dart pub` tool provides the following subcommands: -{% include 'pub-subcommands.md' %} +{% render 'pub-subcommands.md' %} For an overview of all the `dart pub` subcommands, see the [pub tool documentation](/tools/pub/cmd). diff --git a/src/content/libraries/async/using-streams.md b/src/content/libraries/async/using-streams.md index b9381f9132..02dec1d4fd 100644 --- a/src/content/libraries/async/using-streams.md +++ b/src/content/libraries/async/using-streams.md @@ -58,7 +58,7 @@ generating a simple stream of integers using an `async*` function: :::note This page uses embedded DartPads to display runnable examples. -{% include 'dartpads-embedded-troubleshooting.md' %} +{% render 'dartpads-embedded-troubleshooting.md' %} ::: diff --git a/src/content/tools/dart-analyze.md b/src/content/tools/dart-analyze.md index 2faebef21c..1cd75dfdd1 100644 --- a/src/content/tools/dart-analyze.md +++ b/src/content/tools/dart-analyze.md @@ -8,7 +8,7 @@ The `dart analyze` command performs the same [static analysis][] that you get when you use an IDE or editor that has Dart support. -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} Here's an example of performing static analysis over all the Dart files under the current directory: diff --git a/src/content/tools/dart-compile.md b/src/content/tools/dart-compile.md index 956327d807..159b8f017c 100644 --- a/src/content/tools/dart-compile.md +++ b/src/content/tools/dart-compile.md @@ -9,7 +9,7 @@ The output—which you specify using a subcommand—can either include a [Dart runtime][] or be a _module_ (also known as a _snapshot_). -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} Here's an example of using the `exe` subcommand to produce a self-contained executable file (`myapp.exe`): diff --git a/src/content/tools/dart-create.md b/src/content/tools/dart-create.md index 111270afd7..98cc9570ca 100644 --- a/src/content/tools/dart-create.md +++ b/src/content/tools/dart-create.md @@ -8,7 +8,7 @@ The `dart create` command creates a Dart project, using one of several supported templates. The same functionality is available in IDEs. -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} When you run `dart create`, it first creates a directory with the project files. Then it gets package dependencies (unless you specify the `--no-pub` flag). diff --git a/src/content/tools/dart-format.md b/src/content/tools/dart-format.md index 0f117aa740..69eb8a2256 100644 --- a/src/content/tools/dart-format.md +++ b/src/content/tools/dart-format.md @@ -10,7 +10,7 @@ with formatting that follows This is the same formatting that you can get when using an IDE or editor that has Dart support. -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} Provide a list of files or directories to the `dart format` command. For example, here's how to format all the Dart files diff --git a/src/content/tools/dart-info.md b/src/content/tools/dart-info.md index 33cd572a7e..181b5179ce 100644 --- a/src/content/tools/dart-info.md +++ b/src/content/tools/dart-info.md @@ -11,7 +11,7 @@ and project information if in a directory with a `pubspec.yaml`. The output information can be used for debugging tooling issues or reporting a bug. -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} :::warning If you are including the `dart info` output in a bug report, diff --git a/src/content/tools/dart-run.md b/src/content/tools/dart-run.md index 235886d987..cefdc7c210 100644 --- a/src/content/tools/dart-run.md +++ b/src/content/tools/dart-run.md @@ -23,7 +23,7 @@ $ cd myapp $ dart run ``` -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} ## Running a Dart file diff --git a/src/content/tools/dart-test.md b/src/content/tools/dart-test.md index 274af9d19f..3e1d186b13 100644 --- a/src/content/tools/dart-test.md +++ b/src/content/tools/dart-test.md @@ -16,7 +16,7 @@ as described in [Testing Flutter apps][]. [`test` package]: {{site.pub-pkg}}/test [Testing Flutter apps]: {{site.flutter-docs}}/testing -{% include 'tools/dart-tool-note.md' %} +{% render 'tools/dart-tool-note.md' %} Here's an example of using `dart test` to run all tests that are under the current project's `test` directory: diff --git a/src/content/tools/pub/cmd/index.md b/src/content/tools/pub/cmd/index.md index aed331655b..ec3b0fbc53 100644 --- a/src/content/tools/pub/cmd/index.md +++ b/src/content/tools/pub/cmd/index.md @@ -41,7 +41,7 @@ see [Troubleshooting Pub](/tools/pub/troubleshoot). Detailed documentation exists for each of the following pub subcommands: -{% include 'pub-subcommands.md' %} +{% render 'pub-subcommands.md' %} ## Overview of subcommands diff --git a/src/content/tools/pub/cmd/pub-add.md b/src/content/tools/pub/cmd/pub-add.md index 1e25bceb13..fee7385d4a 100644 --- a/src/content/tools/pub/cmd/pub-add.md +++ b/src/content/tools/pub/cmd/pub-add.md @@ -205,7 +205,7 @@ as dev dependencies. ### `--[no-]offline` -{% include 'tools/pub-option-no-offline.md' %} +{% render 'tools/pub-option-no-offline.md' %} ### `-n, --dry-run` @@ -219,4 +219,4 @@ in immediate dependencies (`--precompile`). To prevent precompilation, use `--no-precompile`. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-cache.md b/src/content/tools/pub/cmd/pub-cache.md index 72352e7c17..0b068ea541 100644 --- a/src/content/tools/pub/cmd/pub-cache.md +++ b/src/content/tools/pub/cmd/pub-cache.md @@ -77,4 +77,4 @@ $ dart pub cache add http --version "0.12.2" If `--version` is omitted, pub installs the best of all known versions. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-deps.md b/src/content/tools/pub/cmd/pub-deps.md index cef2d426a6..a55f2a1e83 100644 --- a/src/content/tools/pub/cmd/pub-deps.md +++ b/src/content/tools/pub/cmd/pub-deps.md @@ -78,4 +78,4 @@ Prints all available executables. Generates output in JSON format. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-downgrade.md b/src/content/tools/pub/cmd/pub-downgrade.md index 3d11db1d34..46a5203d55 100644 --- a/src/content/tools/pub/cmd/pub-downgrade.md +++ b/src/content/tools/pub/cmd/pub-downgrade.md @@ -105,11 +105,11 @@ For options that apply to all pub commands, see ### `--[no-]offline` -{% include 'tools/pub-option-no-offline.md' %} +{% render 'tools/pub-option-no-offline.md' %} ### `--dry-run` or `-n` Reports what dependencies would change but doesn't change any. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-get.md b/src/content/tools/pub/cmd/pub-get.md index c56e1084d8..d751f8aef0 100644 --- a/src/content/tools/pub/cmd/pub-get.md +++ b/src/content/tools/pub/cmd/pub-get.md @@ -134,7 +134,7 @@ For options that apply to all pub commands, see ### `--[no-]offline` -{% include 'tools/pub-option-no-offline.md' %} +{% render 'tools/pub-option-no-offline.md' %} ### `--dry-run` or `-n` @@ -154,4 +154,4 @@ Refuses to resolve dependencies with an error message if the `pubspec.lock` file deviates or is missing. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-global.md b/src/content/tools/pub/cmd/pub-global.md index 574b1eabb9..c51b08dbae 100644 --- a/src/content/tools/pub/cmd/pub-global.md +++ b/src/content/tools/pub/cmd/pub-global.md @@ -274,7 +274,7 @@ with the same name. If you don't specify this flag, the preexisting executable will not be replaced. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} [system cache]: /tools/pub/glossary#system-cache [webdev]: /tools/webdev diff --git a/src/content/tools/pub/cmd/pub-lish.md b/src/content/tools/pub/cmd/pub-lish.md index d762009728..77d6d7d383 100644 --- a/src/content/tools/pub/cmd/pub-lish.md +++ b/src/content/tools/pub/cmd/pub-lish.md @@ -37,4 +37,4 @@ To ensure that your package has no warnings before uploading, either don't use `--force`, or use `--dry-run` first. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-outdated.md b/src/content/tools/pub/cmd/pub-outdated.md index 2643d0f1be..03616a5d75 100644 --- a/src/content/tools/pub/cmd/pub-outdated.md +++ b/src/content/tools/pub/cmd/pub-outdated.md @@ -234,7 +234,7 @@ are at the latest version (`--no-up-to-date`). To include up-to-date dependencies, use `--up-to-date`. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} [`args`]: {{site.pub-pkg}}/args [best practices]: /tools/pub/dependencies#best-practices diff --git a/src/content/tools/pub/cmd/pub-remove.md b/src/content/tools/pub/cmd/pub-remove.md index d317095222..7a78fb064a 100644 --- a/src/content/tools/pub/cmd/pub-remove.md +++ b/src/content/tools/pub/cmd/pub-remove.md @@ -26,7 +26,7 @@ For options that apply to all pub commands, see ### `--[no-]offline` -{% include 'tools/pub-option-no-offline.md' %} +{% render 'tools/pub-option-no-offline.md' %} ### `-n, --dry-run` @@ -40,4 +40,4 @@ in immediate dependencies (`--precompile`). To prevent precompilation, use `--no-precompile`. -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-token.md b/src/content/tools/pub/cmd/pub-token.md index 95a6e640e0..be020b277a 100644 --- a/src/content/tools/pub/cmd/pub-token.md +++ b/src/content/tools/pub/cmd/pub-token.md @@ -124,6 +124,6 @@ pub-tokens.json is deleted. Removed 1 secret tokens. ``` -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} [config-dir]: {{site.repo.dart.org}}/cli_util/blob/71ba36e2554f7b7717f3f12b5ddd33751a4e3ddd/lib/cli_util.dart#L88-L118 diff --git a/src/content/tools/pub/cmd/pub-upgrade.md b/src/content/tools/pub/cmd/pub-upgrade.md index cce5d3edcf..178fe724aa 100644 --- a/src/content/tools/pub/cmd/pub-upgrade.md +++ b/src/content/tools/pub/cmd/pub-upgrade.md @@ -109,7 +109,7 @@ For options that apply to all pub commands, see ### `--[no-]offline` -{% include 'tools/pub-option-no-offline.md' %} +{% render 'tools/pub-option-no-offline.md' %} ### `--dry-run` or `-n` @@ -160,4 +160,4 @@ resolved versions, and returns a list of the changed constraints. Can be applied to [specific dependencies](#upgrading-specific-dependencies). -{% include 'pub-problems.md' %} +{% render 'pub-problems.md' %} diff --git a/src/content/tools/sdk.md b/src/content/tools/sdk.md index 9e70b3bf29..e8bc101f7f 100644 --- a/src/content/tools/sdk.md +++ b/src/content/tools/sdk.md @@ -38,7 +38,7 @@ The Dart SDK includes two directories: [`dartaotruntime`](/tools/dartaotruntime) : A Dart runtime for AOT-compiled snapshots. -{% include 'tools/utf-8.md' %} +{% render 'tools/utf-8.md' %} To learn more about the SDK, check out its [README file][readme]. diff --git a/src/content/tutorials/server/get-started.md b/src/content/tutorials/server/get-started.md index 0007abadf6..be59d15f02 100644 --- a/src/content/tutorials/server/get-started.md +++ b/src/content/tutorials/server/get-started.md @@ -27,7 +27,7 @@ console view. Try editing the source code—perhaps you'd like to change the greeting to use another language. :::note -{% include 'dartpad-embedded-troubleshooting.md' %} +{% render 'dartpad-embedded-troubleshooting.md' %} :::