diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6ce71ef84..aba02df61 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,7 +16,7 @@
 1. Fork the repo, develop and test your code.
    See the [github workflow guide].
 1. For _new features_, provide a markdown-based demo following
-   the pattern established in the [demos](demos) directory.
+   the pattern established in the [examples](examples) directory.
    Run `bin/pre-commit.sh` to test your demo.
 1. Submit a pull request.
 
diff --git a/README.md b/README.md
index c53df9b29..6625bac47 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,3 @@
-[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md
-[`make`]: https://www.gnu.org/software/make
-[`sed`]: https://www.gnu.org/software/sed
-[applied]: docs/glossary.md#apply
-[base]: docs/glossary.md#base
-[declarative configuration]: docs/glossary.md#declarative-application-management
-[demo]: demos/README.md
-[demos]: demos/README.md
-[imageBase]: docs/base.jpg
-[imageOverlay]: docs/overlay.jpg
-[install]: INSTALL.md
-[kubernetes style]: docs/glossary.md#kubernetes-style-object
-[kustomization]: docs/glossary.md#kustomization
-[overlay]: docs/glossary.md#overlay
-[overlays]: docs/glossary.md#overlay
-[release page]: https://github.com/kubernetes-sigs/kustomize/releases
-[resource]: docs/glossary.md#resource
-[resources]: docs/glossary.md#resource
-[sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
-[variant]: docs/glossary.md#variant
-[variants]: docs/glossary.md#variant
-[workflows]: docs/workflows.md
-
 # kustomize
 
 `kustomize` lets you customize raw, template-free YAML
@@ -37,7 +14,7 @@ and it's like [`sed`], in that it emits editted text.
 
 **Installation**: Download a binary from the [release
 page], or see these [install] notes. Then try one of
-the tested [demos].
+the tested [examples].
 
 ## Usage
 
@@ -126,16 +103,39 @@ you are a submodule fan).
 
 Generate YAML with
 
-```
+```sh
 kustomize build ~/someApp/overlays/production
 ```
 
 The YAML can be directly [applied] to a cluster:
 
-> ```
+> ```sh
 > kustomize build ~/someApp/overlays/production | kubectl apply -f -
 > ```
 
 ## About
 
 This tool is sponsored by [sig-cli] ([KEP]).
+
+
+[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md
+[`make`]: https://www.gnu.org/software/make
+[`sed`]: https://www.gnu.org/software/sed
+[applied]: docs/glossary.md#apply
+[base]: docs/glossary.md#base
+[declarative configuration]: docs/glossary.md#declarative-application-management
+[examples]: examples/README.md
+[imageBase]: docs/base.jpg
+[imageOverlay]: docs/overlay.jpg
+[install]: INSTALL.md
+[kubernetes style]: docs/glossary.md#kubernetes-style-object
+[kustomization]: docs/glossary.md#kustomization
+[overlay]: docs/glossary.md#overlay
+[overlays]: docs/glossary.md#overlay
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[resource]: docs/glossary.md#resource
+[resources]: docs/glossary.md#resource
+[sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
+[variant]: docs/glossary.md#variant
+[variants]: docs/glossary.md#variant
+[workflows]: docs/workflows.md
diff --git a/bin/pre-commit.sh b/bin/pre-commit.sh
index 66df8f86a..e86273d7a 100755
--- a/bin/pre-commit.sh
+++ b/bin/pre-commit.sh
@@ -43,14 +43,14 @@ function testGoTest {
   go test -v ./...
 }
 
-function testDemos {
-  mdrip --mode test --label test README.md ./demos
+function testExamples {
+  mdrip --mode test --label test README.md ./examples
 }
 
 runTest testGoFmt
 runTest testGoImports
 runTest testGoVet
 runTest testGoTest
-runTest testDemos
+runTest testExamples
 
 exit $rc
diff --git a/demos/README.md b/examples/README.md
similarity index 92%
rename from demos/README.md
rename to examples/README.md
index a44905da5..d5f12fc64 100644
--- a/demos/README.md
+++ b/examples/README.md
@@ -1,6 +1,6 @@
-# Demos
+# Examples
 
-These demos assume that `kustomize` is on your `$PATH`.
+These examples assume that `kustomize` is on your `$PATH`.
 
 They are covered by [pre-commit](../bin/pre-commit.sh)
 tests, and should work with HEAD
diff --git a/demos/breakfast.md b/examples/breakfast.md
similarity index 100%
rename from demos/breakfast.md
rename to examples/breakfast.md
diff --git a/demos/configGeneration.md b/examples/configGeneration.md
similarity index 100%
rename from demos/configGeneration.md
rename to examples/configGeneration.md
diff --git a/demos/helloWorld/README.md b/examples/helloWorld/README.md
similarity index 99%
rename from demos/helloWorld/README.md
rename to examples/helloWorld/README.md
index 025e956bc..9ce98ec0c 100644
--- a/demos/helloWorld/README.md
+++ b/examples/helloWorld/README.md
@@ -51,7 +51,7 @@ mkdir -p $BASE
 
 curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
-/master/demos/helloWorld\
+/master/examples/helloWorld\
 /{configMap,deployment,kustomization,service}.yaml"
 ```
 
diff --git a/demos/helloWorld/configMap.yaml b/examples/helloWorld/configMap.yaml
similarity index 100%
rename from demos/helloWorld/configMap.yaml
rename to examples/helloWorld/configMap.yaml
diff --git a/demos/helloWorld/deployment.yaml b/examples/helloWorld/deployment.yaml
similarity index 100%
rename from demos/helloWorld/deployment.yaml
rename to examples/helloWorld/deployment.yaml
diff --git a/demos/helloWorld/kustomization.yaml b/examples/helloWorld/kustomization.yaml
similarity index 100%
rename from demos/helloWorld/kustomization.yaml
rename to examples/helloWorld/kustomization.yaml
diff --git a/demos/helloWorld/service.yaml b/examples/helloWorld/service.yaml
similarity index 100%
rename from demos/helloWorld/service.yaml
rename to examples/helloWorld/service.yaml
diff --git a/demos/integration_tests.sh b/examples/integration_tests.sh
similarity index 96%
rename from demos/integration_tests.sh
rename to examples/integration_tests.sh
index 7ecc5d82a..6dd62171b 100755
--- a/demos/integration_tests.sh
+++ b/examples/integration_tests.sh
@@ -24,7 +24,7 @@
 #
 # This script assumes that the process running it has
 # checked out the kubernetes-sigs/kustomize repo, and
-# has cd'ed into it (i.e. the directory above "demos")
+# has cd'ed into it (i.e. the directory above "examples")
 # before running it.
 #
 # At time of writing, its 'call point' was in
@@ -79,6 +79,6 @@ function runTest {
 
 setUpEnv
 
-pushd demos
+pushd examples
 runTest ldap/integration_test.sh ldap/base
 popd
diff --git a/demos/ldap/README.md b/examples/ldap/README.md
similarity index 99%
rename from demos/ldap/README.md
rename to examples/ldap/README.md
index 2d302d97e..8d7a4c39d 100644
--- a/demos/ldap/README.md
+++ b/examples/ldap/README.md
@@ -45,7 +45,7 @@ mkdir -p $BASE
 
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
-/master/demos/ldap"
+/master/examples/ldap"
 
 curl -s -o "$BASE/#1" "$CONTENT/base\
 /{deployment.yaml,kustomization.yaml,service.yaml,env.startup.txt}"
diff --git a/demos/ldap/base/deployment.yaml b/examples/ldap/base/deployment.yaml
similarity index 100%
rename from demos/ldap/base/deployment.yaml
rename to examples/ldap/base/deployment.yaml
diff --git a/demos/ldap/base/env.startup.txt b/examples/ldap/base/env.startup.txt
similarity index 100%
rename from demos/ldap/base/env.startup.txt
rename to examples/ldap/base/env.startup.txt
diff --git a/demos/ldap/base/kustomization.yaml b/examples/ldap/base/kustomization.yaml
similarity index 100%
rename from demos/ldap/base/kustomization.yaml
rename to examples/ldap/base/kustomization.yaml
diff --git a/demos/ldap/base/service.yaml b/examples/ldap/base/service.yaml
similarity index 100%
rename from demos/ldap/base/service.yaml
rename to examples/ldap/base/service.yaml
diff --git a/demos/ldap/integration_test.sh b/examples/ldap/integration_test.sh
similarity index 100%
rename from demos/ldap/integration_test.sh
rename to examples/ldap/integration_test.sh
diff --git a/demos/ldap/overlays/production/deployment.yaml b/examples/ldap/overlays/production/deployment.yaml
similarity index 100%
rename from demos/ldap/overlays/production/deployment.yaml
rename to examples/ldap/overlays/production/deployment.yaml
diff --git a/demos/ldap/overlays/production/kustomization.yaml b/examples/ldap/overlays/production/kustomization.yaml
similarity index 100%
rename from demos/ldap/overlays/production/kustomization.yaml
rename to examples/ldap/overlays/production/kustomization.yaml
diff --git a/demos/ldap/overlays/staging/config.env b/examples/ldap/overlays/staging/config.env
similarity index 100%
rename from demos/ldap/overlays/staging/config.env
rename to examples/ldap/overlays/staging/config.env
diff --git a/demos/ldap/overlays/staging/deployment.yaml b/examples/ldap/overlays/staging/deployment.yaml
similarity index 100%
rename from demos/ldap/overlays/staging/deployment.yaml
rename to examples/ldap/overlays/staging/deployment.yaml
diff --git a/demos/ldap/overlays/staging/kustomization.yaml b/examples/ldap/overlays/staging/kustomization.yaml
similarity index 100%
rename from demos/ldap/overlays/staging/kustomization.yaml
rename to examples/ldap/overlays/staging/kustomization.yaml
diff --git a/demos/mySql/README.md b/examples/mySql/README.md
similarity index 99%
rename from demos/mySql/README.md
rename to examples/mySql/README.md
index d9078a55f..1b68e0a17 100644
--- a/demos/mySql/README.md
+++ b/examples/mySql/README.md
@@ -29,7 +29,7 @@ Download them:
 ```
 curl -s  -o "$DEMO_HOME/#1.yaml" "https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
-/master/demos/mySql\
+/master/examples/mySql\
 /{deployment,secret,service}.yaml"
 ```
 
diff --git a/demos/mySql/deployment.yaml b/examples/mySql/deployment.yaml
similarity index 100%
rename from demos/mySql/deployment.yaml
rename to examples/mySql/deployment.yaml
diff --git a/demos/mySql/secret.yaml b/examples/mySql/secret.yaml
similarity index 100%
rename from demos/mySql/secret.yaml
rename to examples/mySql/secret.yaml
diff --git a/demos/mySql/service.yaml b/examples/mySql/service.yaml
similarity index 100%
rename from demos/mySql/service.yaml
rename to examples/mySql/service.yaml
diff --git a/demos/springboot/README.md b/examples/springboot/README.md
similarity index 99%
rename from demos/springboot/README.md
rename to examples/springboot/README.md
index b91b5ead7..ca4dda4ae 100644
--- a/demos/springboot/README.md
+++ b/examples/springboot/README.md
@@ -31,7 +31,7 @@ Download them:
 ```
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
-/master/demos/springboot"
+/master/examples/springboot"
 
 curl -s -o "$DEMO_HOME/#1.yaml" \
   "$CONTENT/base/{deployment,service}.yaml"
diff --git a/demos/springboot/base/deployment.yaml b/examples/springboot/base/deployment.yaml
similarity index 100%
rename from demos/springboot/base/deployment.yaml
rename to examples/springboot/base/deployment.yaml
diff --git a/demos/springboot/base/service.yaml b/examples/springboot/base/service.yaml
similarity index 100%
rename from demos/springboot/base/service.yaml
rename to examples/springboot/base/service.yaml
diff --git a/demos/springboot/overlays/production/application.properties b/examples/springboot/overlays/production/application.properties
similarity index 100%
rename from demos/springboot/overlays/production/application.properties
rename to examples/springboot/overlays/production/application.properties
diff --git a/demos/springboot/overlays/production/healthcheck_patch.yaml b/examples/springboot/overlays/production/healthcheck_patch.yaml
similarity index 100%
rename from demos/springboot/overlays/production/healthcheck_patch.yaml
rename to examples/springboot/overlays/production/healthcheck_patch.yaml
diff --git a/demos/springboot/overlays/production/kustomization.yaml b/examples/springboot/overlays/production/kustomization.yaml
similarity index 100%
rename from demos/springboot/overlays/production/kustomization.yaml
rename to examples/springboot/overlays/production/kustomization.yaml
diff --git a/demos/springboot/overlays/production/memorylimit_patch.yaml b/examples/springboot/overlays/production/memorylimit_patch.yaml
similarity index 100%
rename from demos/springboot/overlays/production/memorylimit_patch.yaml
rename to examples/springboot/overlays/production/memorylimit_patch.yaml
diff --git a/demos/springboot/overlays/production/patch.yaml b/examples/springboot/overlays/production/patch.yaml
similarity index 100%
rename from demos/springboot/overlays/production/patch.yaml
rename to examples/springboot/overlays/production/patch.yaml
diff --git a/demos/springboot/overlays/staging/application.properties b/examples/springboot/overlays/staging/application.properties
similarity index 100%
rename from demos/springboot/overlays/staging/application.properties
rename to examples/springboot/overlays/staging/application.properties
diff --git a/demos/springboot/overlays/staging/kustomization.yaml b/examples/springboot/overlays/staging/kustomization.yaml
similarity index 100%
rename from demos/springboot/overlays/staging/kustomization.yaml
rename to examples/springboot/overlays/staging/kustomization.yaml
diff --git a/demos/springboot/overlays/staging/staging.env b/examples/springboot/overlays/staging/staging.env
similarity index 100%
rename from demos/springboot/overlays/staging/staging.env
rename to examples/springboot/overlays/staging/staging.env