From 18b16ed5ae7731786b5cd6ee2eefc6e7a326ca34 Mon Sep 17 00:00:00 2001
From: Anna Song <annasong@google.com>
Date: Fri, 28 Jul 2023 23:25:56 +0000
Subject: [PATCH 1/5] Restructure existing Reference docs

Restructure Reference section for site to better match k8s.io. Change
descriptions to complete sentences. Improve instructions to locally load
site.
---
 site/README.md                                         |  1 +
 site/content/en/docs/Reference/API/_index.md           |  8 ++++++++
 .../en/docs/Reference/{ => API}/kustomization_file.md  |  4 ++--
 site/content/en/docs/Reference/CLI/_index.md           |  8 ++++++++
 site/content/en/docs/Reference/_index.md               | 10 ++--------
 site/content/en/docs/Reference/glossary.md             |  6 +++---
 site/content/en/docs/Reference/kustomize_cli.md        |  8 --------
 7 files changed, 24 insertions(+), 21 deletions(-)
 create mode 100644 site/content/en/docs/Reference/API/_index.md
 rename site/content/en/docs/Reference/{ => API}/kustomization_file.md (51%)
 create mode 100644 site/content/en/docs/Reference/CLI/_index.md
 delete mode 100644 site/content/en/docs/Reference/kustomize_cli.md

diff --git a/site/README.md b/site/README.md
index 4e90af3215..0004e27353 100644
--- a/site/README.md
+++ b/site/README.md
@@ -12,6 +12,7 @@ The top bar is customized with the sections I think make sense to split. However
 ## Building
 
 Build and run using Docker or Hugo, then access the site at `http://localhost:1313`.
+Please note that this directory contains nested submodules. Follow instructions in [the git submodules documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to initialize.
 
 ### Docker
 Dependencies:
diff --git a/site/content/en/docs/Reference/API/_index.md b/site/content/en/docs/Reference/API/_index.md
new file mode 100644
index 0000000000..872cb1caf8
--- /dev/null
+++ b/site/content/en/docs/Reference/API/_index.md
@@ -0,0 +1,8 @@
+---
+title: "API"
+linkTitle: "API"
+weight: 2
+date: 2023-07-28
+description: >
+  API consists of the resources that specify Kustomize behavior.
+---
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/kustomization_file.md b/site/content/en/docs/Reference/API/kustomization_file.md
similarity index 51%
rename from site/content/en/docs/Reference/kustomization_file.md
rename to site/content/en/docs/Reference/API/kustomization_file.md
index 2e108bf3cc..0bea5c073a 100644
--- a/site/content/en/docs/Reference/kustomization_file.md
+++ b/site/content/en/docs/Reference/API/kustomization_file.md
@@ -2,7 +2,7 @@
 title: "Kustomization File"
 linkTitle: "Kustomization File"
 weight: 1
-date: 2017-01-05
+date: 2023-07-28
 description: >
-  Reference for the Kustomization file
+  The Kustomization file is the entry point for Kustomize execution.
 ---
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/CLI/_index.md b/site/content/en/docs/Reference/CLI/_index.md
new file mode 100644
index 0000000000..e0355fa3fc
--- /dev/null
+++ b/site/content/en/docs/Reference/CLI/_index.md
@@ -0,0 +1,8 @@
+---
+title: "CLI"
+linkTitle: "CLI"
+weight: 3
+date: 2023-07-28
+description: >
+  The command line tools to interact with Kustomize.
+---
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/_index.md b/site/content/en/docs/Reference/_index.md
index f174fc0d05..82a311e96f 100644
--- a/site/content/en/docs/Reference/_index.md
+++ b/site/content/en/docs/Reference/_index.md
@@ -2,13 +2,7 @@
 title: "Reference"
 linkTitle: "Reference"
 weight: 9
+date: 2023-07-28
 description: >
-  Low level reference docs for your project.
+  References are the low-level definitions in Kustomize.
 ---
-
-{{% pageinfo %}}
-This is a placeholder page that shows you how to use this template site.
-{{% /pageinfo %}}
-
-If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen,
-Javadoc, or other doc generation tools by putting them in your `static/` directory. Find out more in [Adding static content](https://docsy.dev/docs/adding-content/content/#adding-static-content). For OpenAPI reference, Docsy also provides a [Swagger UI layout and shortcode](https://www.docsy.dev/docs/adding-content/shortcodes/#swaggerui) that renders [Swagger UI](https://swagger.io/tools/swagger-ui/) using any OpenAPI YAML or JSON file as source.
diff --git a/site/content/en/docs/Reference/glossary.md b/site/content/en/docs/Reference/glossary.md
index 80402fd4ed..92c883c4ae 100644
--- a/site/content/en/docs/Reference/glossary.md
+++ b/site/content/en/docs/Reference/glossary.md
@@ -1,8 +1,8 @@
 ---
 title: "Glossary"
 linkTitle: "Glossary"
-weight: 3
-date: 2017-01-05
+weight: 1
+date: 2023-07-28
 description: >
-  Definitions of the terminology used when interacting with kustomize
+  Glossary defines terminology used to interact with Kustomize.
 ---
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/kustomize_cli.md b/site/content/en/docs/Reference/kustomize_cli.md
deleted file mode 100644
index 8af75a1bbe..0000000000
--- a/site/content/en/docs/Reference/kustomize_cli.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: "kustomize CLI"
-linkTitle: "kustomize CLI"
-weight: 2
-date: 2017-01-05
-description: >
-  Reference for the kustomize CLI
----
\ No newline at end of file

From a91c40a7838fc567ce6816afea6284da906ec792 Mon Sep 17 00:00:00 2001
From: Anna Song <annasong@google.com>
Date: Fri, 28 Jul 2023 23:29:27 +0000
Subject: [PATCH 2/5] Document AnnotationsTransformer on site

Dcoument AnnotationsTransformer API under Reference on site.
---
 .../API/Common Definitions/FieldSpec.md       | 32 +++++++++++++++++++
 .../API/Common Definitions/_index.md          |  8 +++++
 .../Transformers/AnnotationsTransformer.md    | 25 +++++++++++++++
 .../docs/Reference/API/Transformers/_index.md |  8 +++++
 site/content/en/docs/Reference/API/_index.md  |  2 +-
 5 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100644 site/content/en/docs/Reference/API/Common Definitions/FieldSpec.md
 create mode 100644 site/content/en/docs/Reference/API/Common Definitions/_index.md
 create mode 100644 site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md
 create mode 100644 site/content/en/docs/Reference/API/Transformers/_index.md

diff --git a/site/content/en/docs/Reference/API/Common Definitions/FieldSpec.md b/site/content/en/docs/Reference/API/Common Definitions/FieldSpec.md
new file mode 100644
index 0000000000..e459177113
--- /dev/null
+++ b/site/content/en/docs/Reference/API/Common Definitions/FieldSpec.md	
@@ -0,0 +1,32 @@
+---
+title: "FieldSpec"
+linkTitle: "FieldSpec"
+weight: 1
+date: 2023-07-28
+description: >
+  FieldSpec specifies a field for Kustomize to target.
+---
+
+* **group** (string)
+
+  Kubernetes group that this FieldSpec applies to.
+  If empty, this FieldSpec applies to all groups.
+  Currently, there is no way to specify only the core group, which is also represented by the empty string.
+
+* **version** (string)
+
+  Kubernetes version that this FieldSpec applies to.
+  If empty, this FieldSpec applies to all versions.
+
+* **kind** (string)
+
+  Kubernetes kind that this FieldSpec applies to.
+  If empty, this FieldSpec applies to all kinds.
+
+* **path** (string)
+
+  Path to target field. Fields in path are delimited by forward slashes "/".
+
+* **create** (bool)
+
+  If true, creates fields in **path** not already present.
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/API/Common Definitions/_index.md b/site/content/en/docs/Reference/API/Common Definitions/_index.md
new file mode 100644
index 0000000000..239c932799
--- /dev/null
+++ b/site/content/en/docs/Reference/API/Common Definitions/_index.md	
@@ -0,0 +1,8 @@
+---
+title: "Common Definitions"
+linkTitle: "Common Definitions"
+weight: 10
+date: 2023-07-28
+description: >
+  Common definitions are fields used across the Kustomize API.
+---
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md b/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md
new file mode 100644
index 0000000000..a44d6fca9d
--- /dev/null
+++ b/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md
@@ -0,0 +1,25 @@
+---
+title: "AnnotationsTransformer"
+linkTitle: "AnnotationsTransformer"
+weight: 1
+date: 2023-07-28
+description: >
+  AnnotationsTransformer adds annotations to user-input resources.
+---
+
+* **apiVersion**: builtin
+* **kind**: AnnotationsTransformer
+* **metadata** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta))
+
+  Standard object's metadata.
+
+* **annotations** (map[string]string)
+
+  Map of annotations that AnnotationsTransformer will add to resources.
+
+* **fieldSpecs** (\[\][FieldSpec]({{< relref "../Common%20Definitions/FieldSpec.md" >}}))
+
+  fieldSpecs specifies the field on each resource that AnnotationsTransformer should add the annotations to.
+  It essentially allows the user to re-define the field path of the Kubernetes annotations field from `metadata/annotations` for different resources.
+
+  If not specified, AnnotationsTransformer applies the annotations to the `metadata/annotations` field of all resources.
diff --git a/site/content/en/docs/Reference/API/Transformers/_index.md b/site/content/en/docs/Reference/API/Transformers/_index.md
new file mode 100644
index 0000000000..17bed435f8
--- /dev/null
+++ b/site/content/en/docs/Reference/API/Transformers/_index.md
@@ -0,0 +1,8 @@
+---
+title: "Transformers"
+linkTitle: "Transformers"
+weight: 3
+date: 2023-07-28
+description: >
+  Transformers have the ability to modify user-input resources.
+---
\ No newline at end of file
diff --git a/site/content/en/docs/Reference/API/_index.md b/site/content/en/docs/Reference/API/_index.md
index 872cb1caf8..715950b4d7 100644
--- a/site/content/en/docs/Reference/API/_index.md
+++ b/site/content/en/docs/Reference/API/_index.md
@@ -4,5 +4,5 @@ linkTitle: "API"
 weight: 2
 date: 2023-07-28
 description: >
-  API consists of the resources that specify Kustomize behavior.
+  The Kustomize API is the set of custom resources that define its behavior.
 ---
\ No newline at end of file

From 70fb197a4f0e716caa1dd91b5ee58d2de6eae9ce Mon Sep 17 00:00:00 2001
From: Anna Song <annasong@google.com>
Date: Fri, 1 Sep 2023 19:58:10 +0000
Subject: [PATCH 3/5] Document required fields

Document required fields and explain effects of optional ones.
---
 .../API/Transformers/AnnotationsTransformer.md         |  4 ++++
 .../en/docs/Reference/API/Transformers/_index.md       | 10 +++++++++-
 site/content/en/docs/Reference/API/_index.md           |  5 ++++-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md b/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md
index a44d6fca9d..901482bc5c 100644
--- a/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md
+++ b/site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md
@@ -7,6 +7,8 @@ description: >
   AnnotationsTransformer adds annotations to user-input resources.
 ---
 
+See [Transformers]({{< relref "../Transformers" >}}) for common required fields.
+
 * **apiVersion**: builtin
 * **kind**: AnnotationsTransformer
 * **metadata** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta))
@@ -17,6 +19,8 @@ description: >
 
   Map of annotations that AnnotationsTransformer will add to resources.
 
+  If not specified, AnnotationsTransformer leaves the resources unchanged.
+
 * **fieldSpecs** (\[\][FieldSpec]({{< relref "../Common%20Definitions/FieldSpec.md" >}}))
 
   fieldSpecs specifies the field on each resource that AnnotationsTransformer should add the annotations to.
diff --git a/site/content/en/docs/Reference/API/Transformers/_index.md b/site/content/en/docs/Reference/API/Transformers/_index.md
index 17bed435f8..c6d0ea83b2 100644
--- a/site/content/en/docs/Reference/API/Transformers/_index.md
+++ b/site/content/en/docs/Reference/API/Transformers/_index.md
@@ -5,4 +5,12 @@ weight: 3
 date: 2023-07-28
 description: >
   Transformers have the ability to modify user-input resources.
----
\ No newline at end of file
+---
+
+Transformers are Kubernetes objects that dictate how Kustomize changes other Kubernetes objects that users provide.
+The following required Kubernetes fields are also required on transformers:
+
+* `apiVersion`
+* `kind`
+* `metadata`
+  * `name`
diff --git a/site/content/en/docs/Reference/API/_index.md b/site/content/en/docs/Reference/API/_index.md
index 715950b4d7..058ebd3d19 100644
--- a/site/content/en/docs/Reference/API/_index.md
+++ b/site/content/en/docs/Reference/API/_index.md
@@ -5,4 +5,7 @@ weight: 2
 date: 2023-07-28
 description: >
   The Kustomize API is the set of custom resources that define its behavior.
----
\ No newline at end of file
+---
+
+This section contains user-friendly definitions of resources custom to Kustomize that define its behavior.
+Required fields are marked as such.

From 2e5a885741d32f8a554cac21a45890ebbd9ea177 Mon Sep 17 00:00:00 2001
From: Anna Song <annasong@google.com>
Date: Fri, 1 Sep 2023 19:58:42 +0000
Subject: [PATCH 4/5] Make site setup instructions more explicit

---
 site/README.md | 36 +++++++++++++++++++++++-------------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/site/README.md b/site/README.md
index 0004e27353..e69427060a 100644
--- a/site/README.md
+++ b/site/README.md
@@ -12,7 +12,6 @@ The top bar is customized with the sections I think make sense to split. However
 ## Building
 
 Build and run using Docker or Hugo, then access the site at `http://localhost:1313`.
-Please note that this directory contains nested submodules. Follow instructions in [the git submodules documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to initialize.
 
 ### Docker
 Dependencies:
@@ -24,17 +23,28 @@ docker-compomse up -d
 ```
 
 ### hugo
-Building using the `hugo` command requires the following dependencies:
-* [hugo CLI](https://gohugo.io/getting-started/installing/)
-* [Go](https://go.dev/learn/)
-* [Node.js](https://nodejs.org/en/)
-* npm dependencies
+1. Building using the `hugo` command requires the following dependencies:
+  * [hugo CLI](https://gohugo.io/getting-started/installing/)
+  * [Go](https://go.dev/learn/)
+  * [Node.js](https://nodejs.org/en/)
+  * npm dependencies
+     ```bash
+     npm install -D autoprefixer
+     npm install -D postcss-cli
+     npm install -D postcss
+     ```
+1. Initialize [Docsy](https://www.docsy.dev/docs/) and nested [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
    ```bash
-   npm install -D autoprefixer
-   npm install -D postcss-cli
-   npm install -D postcss
+   # In Kustomize repository root directory, fetch docsy submodule at site/themes/docsy.
+   # See alternative submodule cloning options in the submodule documentation linked above.
+   git submodule init
+   git submodule update
+   # Fetch submodules nested in docsy.
+   cd site/themes/docsy
+   git submodule init
+   git submodule update
+   ```
+1. Start in development mode:
+   ```bash
+   hugo serve -D
    ```
-Start in development mode:
-```bash
-hugo serve -D
-```

From 4267aa45ec3b6ed1df6d28af573a153bbb403af3 Mon Sep 17 00:00:00 2001
From: Anna Song <annasong@google.com>
Date: Fri, 8 Sep 2023 17:22:03 +0000
Subject: [PATCH 5/5] Link required K8s fields

---
 site/content/en/docs/Reference/API/Transformers/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/content/en/docs/Reference/API/Transformers/_index.md b/site/content/en/docs/Reference/API/Transformers/_index.md
index c6d0ea83b2..3fc3168e8e 100644
--- a/site/content/en/docs/Reference/API/Transformers/_index.md
+++ b/site/content/en/docs/Reference/API/Transformers/_index.md
@@ -8,7 +8,7 @@ description: >
 ---
 
 Transformers are Kubernetes objects that dictate how Kustomize changes other Kubernetes objects that users provide.
-The following required Kubernetes fields are also required on transformers:
+Besides `spec`, transformers require the same [fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/#required-fields), listed below, as other Kubernetes objects:
 
 * `apiVersion`
 * `kind`