docs preview: bazelbuild/bazel#28437

community/partners.mdx

@@ -34,28 +34,24 @@ EngFlow is the build and test acceleration company created by core Bazel enginee
 Develocity is a multi-build-system platform for improving developer productivity and happiness. It does this by providing a comprehensive and end-to-end solution for build & test observability, acceleration, and failure analytics, and currently supports the Bazel, Apache Maven, Gradle, and SBT build systems. Specifically, Develocity for Bazel supports Build Cache to speed up build and test feedback cycles; Build Scan® that is like an X-ray for your build to make troubleshooting more efficient; and Failure Analytics to improve toolchain reliability.
 
 </Card>
-<Card title="JetBrains" img="/community/images/jetbrains.svg" cta="Learn more" href="https://www.jetbrains.com/help/idea/bazel.html">
-JetBrains is a leading provider of IDEs and developer tools. Since 2022, we’ve been active in the Bazel community, delivering robust polyglot support through plugins for CLion, GoLand, PyCharm, and IntelliJ IDEA. These plugins provide deep Bazel integration for large projects, enabling editing, navigation, testing, and debugging across multiple languages, including C++, Go, Python, Java, Kotlin, Scala, as well as Starlark and other configuration files.
+<Card title="Tweag" img="/community/images/tweag-logo.png" cta="Learn more" href="https://www.tweag.io/group/scalable-builds/">
+Tweag is one of Bazel's earliest adopters, an active contributor of new features and new open source extensions since early 2018. We have been helping companies and teams achieve near byte-for-byte reproducibility, fully traceable all the way to production and conveniently auditable builds that can be cached correctly and run fast. Besides our consulting work, we also have an array of tools and extensions. Skyscope to visualize and explore complex Bazel build graphs with hundreds of thousands of nodes in your web browser. Open source Bazel extensions to achieve fully reproducible builds with the power of Nix, manage shell tools in a principled way, and build Haskell projects with Bazel. Finally, our open source Gazelle extensions to automate your Bazel migration and build maintenance.
 
 </Card>
 </Columns>
 
 <Columns cols={2}>
-<Card title="Tweag" img="/community/images/tweag-logo.png" cta="Learn more" href="https://www.tweag.io/group/scalable-builds/">
-Tweag is one of Bazel's earliest adopters, an active contributor of new features and new open source extensions since early 2018. We have been helping companies and teams achieve near byte-for-byte reproducibility, fully traceable all the way to production and conveniently auditable builds that can be cached correctly and run fast. Besides our consulting work, we also have an array of tools and extensions. Skyscope to visualize and explore complex Bazel build graphs with hundreds of thousands of nodes in your web browser. Open source Bazel extensions to achieve fully reproducible builds with the power of Nix, manage shell tools in a principled way, and build Haskell projects with Bazel. Finally, our open source Gazelle extensions to automate your Bazel migration and build maintenance.
-
-</Card>
 <Card title="Nativelink" img="/community/images/nativelink.svg" cta="Learn more" href="https://www.nativelink.com/">
 NativeLink is the 100% free, open source, and permissively licensed build and test acceleration project written in Rust. It is created by a team of open source maintainers and the company is funded by Wellington Management, an asset manager with over one trillion dollars under management. Whether deployed on your infrastructure or on NativeLink’s cloud, our global Bazel, Reclient, and compiler experts provide 24x7 coverage, support small and large teams, and SSO included.
 
 </Card>
-</Columns>
-
-<Columns cols={2}>
 <Card title="VirtusLab" img="/community/images/virtuslab.svg" cta="Learn more" href="https://virtuslab.com/expertise/monorepo-expertise-with-bazel/">
 VirtusLab specializes in managing monorepos and migrating codebases to Bazel. We offer a smooth transition that enhances your software’s creation, testing, and release processes. Our engineers will assist you in adopting industry-standard tooling and practices, including top-tier security measures. We believe that a seamless Developer Experience requires great tooling. By partnering with us, you will optimize build times, reduce costs, and empower your development teams to reach their peak performance.
 
 </Card>
+</Columns>
+
+<Columns cols={2}>
 <Card title="Buildkite" img="/community/images/buildkite.svg" cta="Learn more" href="https://buildkite.com/">
 Based in San Francisco and Sydney, Buildkite is a fast-growing software delivery provider that offers the industry’s first and only Scale-Out Delivery Platform. Buildkite's Scale-Out Delivery platform is the only solution that provides the flexibility and scale required by the world's most demanding companies for delivering software across a broad range of use cases, including AI/ML workloads and mobile application development. Global innovation leaders including Airbnb, Block, Canva, Cruise, Culture Amp, Elastic, Lyft, PagerDuty, Pinterest, PlanetScale, Rippling, Shopify, Slack, Tinder, Twilio, Uber, and Wayfair have standardized on Buildkite for software delivery. Buildkite delivers seamless Bazel integration, enabling teams to scale CI/CD for complex monorepos. Buildkite sponsors CI for the Bazel project as part of its commitment to developers, driving faster builds and broader adoption.
 

community/users.mdx

@@ -51,7 +51,7 @@ ASML is an innovation leader in the semiconductor industry. We provide chipmaker
 with everything they need – hardware, software and services – to mass produce
 patterns on silicon through lithography.
 
-### [Augment Code](https://augmentcode.com)
+### [Augment Code](https://augmentcode.com){: .external}
 
 Augment Code is the first Developer AI for teams.
 Every Augment feature is context aware. Every suggestion, completion, and
@@ -223,6 +223,11 @@ creating huge simulations inhabited by millions of complex entities.
 InteraXon is a thought-controlled computing firm that creates hardware and
 software platforms to convert brainwaves into digital signals.
 
+## [JetBrains](https://www.jetbrains.com/)
+<img src="/community/images/jetbrains.svg" width="150" align="right" />
+
+JetBrains is a leading provider of IDEs and developer tools. Since 2022, we’ve been active in the Bazel community, delivering robust polyglot support through plugins for CLion, GoLang, PyCharm, and IntelliJ IDEA. We also use Bazel internally to build these products from our own large-scale monorepo.
+
 ### [Jupiter](https://jupiter.co/)
 
 Jupiter is a company that provides delivery of groceries and household
@@ -747,4 +752,4 @@ architecture.
 ### [ZhihuDailyPurify](https://github.com/izzyleung/ZhihuDailyPurify)
 
 ZhihuDailyPurify is a light weight version of Zhihu Daily, a Chinese
-question-and-answer webs.
+question-and-answer webs.

concepts/build-files.mdx

@@ -0,0 +1,152 @@
+---
+title: 'BUILD files'
+---
+
+
+
+The previous sections described packages, targets and labels, and the
+build dependency graph abstractly. This section describes the concrete syntax
+used to define a package.
+
+By definition, every package contains a `BUILD` file, which is a short
+program.
+
+Note: The `BUILD` file can be named either `BUILD` or `BUILD.bazel`. If both
+files exist, `BUILD.bazel` takes precedence over `BUILD`.
+For simplicity's sake, the documentation refers to these files simply as `BUILD`
+files.
+
+`BUILD` files are evaluated using an imperative language,
+[Starlark](https://github.com/bazelbuild/starlark/){: .external}.
+
+They are interpreted as a sequential list of statements.
+
+In general, order does matter: variables must be defined before they are
+used, for example. However, most `BUILD` files consist only of declarations of
+build rules, and the relative order of these statements is immaterial; all
+that matters is _which_ rules were declared, and with what values, by the
+time package evaluation completes.
+
+When a build rule function, such as `cc_library`, is executed, it creates a
+new target in the graph. This target can later be referred using a label.
+
+In simple `BUILD` files, rule declarations can be re-ordered freely without
+changing the behavior.
+
+To encourage a clean separation between code and data, `BUILD` files cannot
+contain function definitions, `for` statements or `if` statements (but list
+comprehensions and `if` expressions are allowed). Functions can be declared in
+`.bzl` files instead. Additionally, `*args` and `**kwargs` arguments are not
+allowed in `BUILD` files; instead list all the arguments explicitly.
+
+Crucially, programs in Starlark can't perform arbitrary I/O. This invariant
+makes the interpretation of `BUILD` files hermetic — dependent only on a known
+set of inputs, which is essential for ensuring that builds are reproducible.
+For more details, see [Hermeticity](/basics/hermeticity).
+
+Because `BUILD` files need to be updated whenever the dependencies of the
+underlying code change, they are typically maintained by multiple people on a
+team. `BUILD` file authors should comment liberally to document the role
+of each build target, whether or not it is intended for public use, and to
+document the role of the package itself.
+
+## Loading an extension
+
+Bazel extensions are files ending in `.bzl`. Use the `load` statement to import
+a symbol from an extension.
+
+```
+load("//foo/bar:file.bzl", "some_library")
+```
+
+This code loads the file `foo/bar/file.bzl` and adds the `some_library` symbol
+to the environment. This can be used to load new rules, functions, or constants
+(for example, a string or a list). Multiple symbols can be imported by using
+additional arguments to the call to `load`. Arguments must be string literals
+(no variable) and `load` statements must appear at top-level — they cannot be
+in a function body.
+
+The first argument of `load` is a [label](/concepts/labels) identifying a
+`.bzl` file. If it's a relative label, it is resolved with respect to the
+package (not directory) containing the current `bzl` file. Relative labels in
+`load` statements should use a leading `:`.
+
+`load` also supports aliases, therefore, you can assign different names to the
+imported symbols.
+
+```
+load("//foo/bar:file.bzl", library_alias = "some_library")
+```
+
+You can define multiple aliases within one `load` statement. Moreover, the
+argument list can contain both aliases and regular symbol names. The following
+example is perfectly legal (please note when to use quotation marks).
+
+```
+load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
+```
+
+In a `.bzl` file, symbols starting with `_` are not exported and cannot be
+loaded from another file.
+
+You can use [load visibility](/concepts/visibility#load-visibility) to restrict
+who may load a `.bzl` file.
+
+## Types of build rules
+
+The majority of build rules come in families, grouped together by
+language. For example, `cc_binary`, `cc_library`
+and `cc_test` are the build rules for C++ binaries,
+libraries, and tests, respectively. Other languages use the same
+naming scheme, with a different prefix, such as `java_*` for
+Java. Some of these functions are documented in the
+[Build Encyclopedia](/reference/be/overview), but it is possible
+for anyone to create new rules.
+
+* `*_binary` rules build executable programs in a given language. After a
+  build, the executable will reside in the build tool's binary
+  output tree at the corresponding name for the rule's label,
+  so `//my:program` would appear at (for example) `$(BINDIR)/my/program`.
+
+  In some languages, such rules also create a runfiles directory
+  containing all the files mentioned in a `data`
+  attribute belonging to the rule, or any rule in its transitive
+  closure of dependencies; this set of files is gathered together in
+  one place for ease of deployment to production.
+
+* `*_test` rules are a specialization of a `*_binary` rule, used for automated
+  testing. Tests are simply programs that return zero on success.
+
+  Like binaries, tests also have runfiles trees, and the files
+  beneath it are the only files that a test may legitimately open
+  at runtime. For example, a program `cc_test(name='x',
+  data=['//foo:bar'])` may open and read `$TEST_SRCDIR/workspace/foo/bar` during execution.
+  (Each programming language has its own utility function for
+  accessing the value of `$TEST_SRCDIR`, but they are all
+  equivalent to using the environment variable directly.)
+  Failure to observe the rule will cause the test to fail when it is
+  executed on a remote testing host.
+
+* `*_library` rules specify separately-compiled modules in the given
+    programming language. Libraries can depend on other libraries,
+    and binaries and tests can depend on libraries, with the expected
+    separate-compilation behavior.
+
+<table class="columns">
+  <tr>
+    <td><a class="button button-with-icon button-primary"
+           href="/concepts/labels">
+        <span class="material-icons" aria-hidden="true">arrow_back</span>Labels</a>
+    </td>
+    <td><a class="button button-with-icon button-primary"
+           href="/concepts/dependencies">
+        Dependencies<span class="material-icons icon-after" aria-hidden="true">arrow_forward</span></a>
+    </td>
+  </tr>
+</table>
+
+## File encoding
+
+`BUILD` and `.bzl` files should be encoded in UTF-8, of which ASCII is a valid
+subset. Arbitrary byte sequences are currently allowed, but may stop being
+supported in the future.