Docs: Add intros to Skylark files
PiperOrigin-RevId: 350860130
diff --git a/site/docs/skylark/aspects.md b/site/docs/skylark/aspects.md
index a94ad4e..3754ddf 100644
--- a/site/docs/skylark/aspects.md
+++ b/site/docs/skylark/aspects.md
@@ -5,6 +5,9 @@
# Aspects
+This page explains the basics and benefits of using aspects and provides
+simple and advanced examples.
+
Aspects allow augmenting build dependency graphs with additional information
and actions. Some typical scenarios when aspects can be useful:
diff --git a/site/docs/skylark/language.md b/site/docs/skylark/language.md
index 7439e37..54a8a66 100644
--- a/site/docs/skylark/language.md
+++ b/site/docs/skylark/language.md
@@ -7,7 +7,7 @@
<!-- [TOC] -->
-The page is an overview of [Starlark](https://github.com/bazelbuild/starlark),
+This page is an overview of [Starlark](https://github.com/bazelbuild/starlark),
formerly known as Skylark, the language used in Bazel. For a complete list of
functions and types, check [Starlark's API reference](lib/skylark-overview.html).
diff --git a/site/docs/skylark/macros.md b/site/docs/skylark/macros.md
index 946ed61..662ab35 100644
--- a/site/docs/skylark/macros.md
+++ b/site/docs/skylark/macros.md
@@ -6,6 +6,9 @@
# Macros
+This page covers the basics of using macros and includes typical use cases,
+debugging, and conventions.
+
A macro is a function called from the BUILD file that can instantiate rules.
Macros are mainly used for encapsulation and code reuse of existing rules
and other macros. By the end of the
diff --git a/site/docs/skylark/repository_rules.md b/site/docs/skylark/repository_rules.md
index 746a66e..d2d8df3 100644
--- a/site/docs/skylark/repository_rules.md
+++ b/site/docs/skylark/repository_rules.md
@@ -4,6 +4,9 @@
---
# Repository rules
+This page covers how to create repository rules and provides examples for
+more details.
+
An [external repository](../external.md) is a rule that can be used only
in the `WORKSPACE` file and enables non-hermetic operation at the loading phase
of Bazel. Each external repository rule creates its own workspace, with its
diff --git a/site/docs/skylark/windows_tips.md b/site/docs/skylark/windows_tips.md
index da8ae80..dd2ddef 100644
--- a/site/docs/skylark/windows_tips.md
+++ b/site/docs/skylark/windows_tips.md
@@ -5,9 +5,8 @@
# Writing rules on Windows
-Common problems of writing portable rules, and some solutions.
-
-This document focuses on writing Windows-compatible rules.
+This page focuses on writing Windows-compatible rules, common problems of
+writing portable rules, and some solutions.
## Paths
