Use mounts instead of symlinks to share content

Natalie Arellano · Natalie Arellano · commit 56f074b5f122 · 2024-02-29T13:00:41.000-05:00
This seems to be the recommended way of doing it with Hugo

Also fixes sidebar ordering for Platform Operator section

Signed-off-by: Natalie Arellano &lt;narellano@vmware.com&gt;
diff --git a/config.toml b/config.toml
@@ -91,3 +91,23 @@ featureKatacoda = false
   [security.http]
     methods = ['(?i)GET|POST']
     urls = ['.*']
+
+# For more information, see https://gohugo.io/getting-started/directory-structure/#union-file-system
+[[module.mounts]]
+    source = 'content'
+    target = 'content'
+[[module.mounts]]
+    source = 'content/docs/.concepts/buildpack.md'
+    target = 'content/docs/for-app-developers/concepts/buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.concepts/buildpack.md'
+    target = 'content/docs/for-buildpack-authors/concepts/buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.concepts/buildpack.md'
+    target = 'content/docs/for-platform-operators/concepts/buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.concepts/extension.md'
+    target = 'content/docs/for-buildpack-authors/concepts/extension.md'
+[[module.mounts]]
+    source = 'content/docs/.concepts/extension.md'
+    target = 'content/docs/for-platform-operators/concepts/extension.md'
diff --git a/content/docs/.concepts/buildpack.md b/content/docs/.concepts/buildpack.md
@@ -0,0 +1,54 @@
++++
+title="What is a buildpack?"
+weight=1
++++
+
+A `buildpack` is software that transforms application source code into runnable artifacts
+by analyzing the code and determining the best way to build it.
+
+<!--more-->
+
+![buildpacks](/images/what.svg)
+
+## Why buildpacks?
+
+Buildpacks allow application developers to focus on what they do best - writing code, without having to worry about image security, optimizing container images, or container build strategy.
+
+How much time have you spent struggling to wrangle yet another Dockerfile? Copying and pasting random Dockerfile snippets into every project? Buildpacks can help! They are a better approach to building container images for applications.
+
+## What do they look like?
+
+Typical buildpacks consist of at least three files:
+
+* `buildpack.toml` -- provides metadata about the buildpack, containing information such as its name, ID, and version.
+* `bin/detect` -- performs [detect](#detect).
+* `bin/build` -- performs [build](#build).
+
+## How do they work?
+
+![how](/images/how.svg)
+
+**Each buildpack has two jobs to do**
+
+### Detect
+
+The buildpack determines if it is needed or not.
+
+For example:
+
+- A Python buildpack may look for a `requirements.txt` or a `setup.py` file.
+- A Node buildpack may look for a `package-lock.json` file.
+
+### Build
+
+The buildpack transforms application source code in some way, for example by
+
+- Setting build-time and run-time environment variables.
+- Downloading dependencies.
+- Running source code compilation (if needed).
+- Configuring the application entrypoint and any startup scripts.
+
+For example:
+
+- A Python buildpack may run `pip install -r requirements.txt` if it detected a `requirements.txt` file.
+- A Node buildpack may run `npm install` if it detected a `package-lock.json` file.
diff --git a/content/docs/.concepts/extension.md b/content/docs/.concepts/extension.md
@@ -1,17 +1,17 @@
 
 +++
-title="What are image extensions?"
+title="What is an image extension?"
 aliases=[
   "/docs/features/dockerfiles"
 ]
 weight=99
 +++
 
-Image extensions generate Dockerfiles that can be used to extend base images for buildpacks builds.
+An `image extension` is software that generates Dockerfiles that can be used to extend base images for buildpacks builds.
 
 <!--more-->
 
-## Why Dockerfiles?
+## Why image extensions?
 
 Buildpacks can do a lot, but there are some things buildpacks can't do. They can't install operating system packages,
 for example. Why not?
@@ -24,7 +24,7 @@ possible.
 This has been a longstanding source of [discussion](https://github.com/buildpacks/rfcs/pull/173) within the CNB project:
 how can we preserve the benefits of buildpacks while enabling more powerful capabilities?
 
-## Buildpacks and Dockerfiles can work together
+### Buildpacks and Dockerfiles can work together
 
 Buildpacks are often presented as an alternative to Dockerfiles, but we think buildpacks and Dockerfiles can work
 together.
@@ -36,20 +36,11 @@ installing OS-level dependencies for containers.
 The CNB Dockerfiles feature allows Dockerfiles to "provide" dependencies that buildpacks "require" through a
 shared [build plan](/docs/reference/spec/buildpack-api/#build-plan), by introducing the concept of image extensions.
 
-## What are image extensions?
+## What do they look like?
 
 Image extensions are buildpack-like components that use a restricted `Dockerfile` syntax to expand base images. Their
 purpose is to generate Dockerfiles that can be used to extend the builder or run images prior to buildpacks builds.
 
-Like buildpacks, extensions participate in the `detect` phase - analyzing application source code to determine if they
-are needed. During `detect`, extensions can contribute to
-the [build plan](/docs/reference/spec/buildpack-api/#build-plan) - recording dependencies that they are able to "
-provide" (though unlike buildpacks, they can't "require" anything).
-
-If the provided order contains extensions, the output of `detect` will be a group of image extensions and a group of
-buildpacks that together produce a valid build plan. Image extensions only generate Dockerfiles - they don't create
-layers or participate in the `build` phase.
-
 An image extension could be defined with the following directory:
 
 ```
@@ -60,57 +51,32 @@ An image extension could be defined with the following directory:
 │   ├── generate   <- similar to a buildpack ./bin/build
 ```
 
-* The `extension.toml` describes the extension, containing information such as its name, ID, and version.
-* `./bin/detect` is invoked during the `detect` phase. It analyzes application source code to determine if the extension
+* The `extension.toml` provides metadata about the extension, containing information such as its name, ID, and version.
+* `./bin/detect` performs [detect](#detect). It analyzes application source code to determine if the extension
   is needed and contributes build plan entries.
-* `./bin/generate` is invoked during the `generate` phase (a new lifecycle phase that happens after `detect`). It
+* `./bin/generate` performs [generate](#generate) (a new lifecycle phase that happens after `detect`). It
   outputs either or both of `build.Dockerfile` or `run.Dockerfile` for extending the builder or run image.
 
-For more information and to see a build in action,
-see [authoring an image extension](/docs/for-buildpack-authors/tutorials/basic-extension).
-
-## A platform's perspective
-
-Platforms may wish to use image extensions if they wish to provide the flexibility of modifying base images dynamically
-at build time.
-
-### Risks
+## How do they work?
 
-Image extensions are considered experimental and susceptible to change in future API versions. However, image extension
-should be **used with great care**. Platform operators should be mindful that:
+**Each image extension has two jobs to do**
 
-* Dockerfiles are very powerful - in fact, you can do anything with a Dockerfile! Introducing image extensions into your
-  CNB builds can eliminate the security and compatibility guarantees that buildpacks provide.
-* When Dockerfiles are used to switch the run image from that defined on the provided builder, the resulting run image
-  may not have all the mixins required by buildpacks that detected. Platforms may wish to optionally re-validate mixins
-  prior to `build` when using extensions.
+### Detect
 
-### Putting it all together
+The extension determines if it is needed or not.
 
-The ordering of lifecycle phases looks like the following:
-
-* `analyze`
-* `detect` - after standard detection, `detect` will also run extensions' `./bin/generate`; output Dockerfiles are
-  written to a volume
-* `restore`
-* `extend` - applies one or more `build.Dockerfile`s to the builder image
-* `extend` - applies one or more `run.Dockerfile`s to the run image (could run in parallel with builder image extension)
-* `build`
-* `export`
-
-For more information, consult the [migration guide](/docs/for-platform-operators/how-to/migrate/platform-api-0.9-0.10).
-
-#### Platform support for Dockerfiles
-
-Supported:
+Like buildpacks, extensions participate in the `detect` phase - analyzing application source code to determine if they
+are needed. During `detect`, extensions can contribute to
+the [build plan](/docs/reference/spec/buildpack-api/#build-plan) - recording dependencies that they are able to "
+provide" (though unlike buildpacks, they can't "require" anything).
 
-* [pack cli](https://github.com/buildpacks/pack) (prefer version `0.30.0` and above)
+If the provided order contains extensions, the output of `detect` will be a group of image extensions and a group of
+buildpacks that together produce a valid build plan. Image extensions only generate Dockerfiles - they don't create
+layers or participate in the `build` phase.
 
-Needs support:
+### Generate
 
-* [Tekton task](https://github.com/tektoncd/catalog/tree/main/task/buildpacks-phases/0.2) ([GitHub issue](https://github.com/tektoncd/catalog/issues/1096))
-* [kpack](https://github.com/pivotal/kpack) ([GitHub issue](https://github.com/pivotal/kpack/issues/1047))
+The extension outputs Dockerfiles that can be used to extend either or both of the build-time base image and the runtime base image.
 
-Your feedback is appreciated! As the feature evolves, we want to hear from you - what's going well, what's challenging,
-and anything else you'd like to see. Please reach out in [Slack](https://cncf.slack.io) (#buildpacks channel)
-or [GitHub](https://github.com/buildpacks).
+For more information and to see a build in action,
+see [authoring an image extension](/docs/for-buildpack-authors/tutorials/basic-extension).
diff --git a/content/docs/for-app-developers/concepts/buildpack.md b/content/docs/for-app-developers/concepts/buildpack.md
diff --git a/content/docs/for-app-developers/how-to/_index.md b/content/docs/for-app-developers/how-to/_index.md
@@ -1,6 +1,5 @@
 +++
 title="How To"
 weight=3
-
 include_summaries=true
 +++
diff --git a/content/docs/for-buildpack-authors/concepts/_index.md b/content/docs/for-buildpack-authors/concepts/_index.md
@@ -1,6 +1,5 @@
 +++
 title="Concepts"
 weight=2
-
 include_summaries=true
 +++
diff --git a/content/docs/for-buildpack-authors/concepts/buildpack.md b/content/docs/for-buildpack-authors/concepts/buildpack.md
diff --git a/content/docs/for-buildpack-authors/concepts/extension.md b/content/docs/for-buildpack-authors/concepts/extension.md
diff --git a/content/docs/for-buildpack-authors/how-to/_index.md b/content/docs/for-buildpack-authors/how-to/_index.md
@@ -1,6 +1,5 @@
 +++
 title="How To"
 weight=3
-
 include_summaries=true
 +++
diff --git a/content/docs/for-platform-operators/concepts/_index.md b/content/docs/for-platform-operators/concepts/_index.md
@@ -1,5 +1,5 @@
 +++
 title="Concepts"
-weight=1
+weight=2
 include_summaries=true
 +++
diff --git a/content/docs/for-platform-operators/concepts/buildpack.md b/content/docs/for-platform-operators/concepts/buildpack.md
diff --git a/content/docs/for-platform-operators/how-to/_index.md b/content/docs/for-platform-operators/how-to/_index.md
@@ -1,6 +1,5 @@
 +++
 title="How To"
 weight=3
-
 include_summaries=true
 +++
