Improve formatting

Signed-off-by: Natalie Arellano <[email protected]>

Author: Natalie Arellano

content/docs/extension-author-guide/create-extension/_index.md

@@ -17,7 +17,7 @@ Before we get started, make sure you've got the following installed:
 
 This is a step-by-step tutorial for creating a CNB Image Extension for `curl`.
 
-- [Set up your local environment](/docs/buildpack-author-guide/create-buildpack/setup-local-environment)
+- [Set up your local environment](/docs/extension-author-guide/create-extension/setup-local-environment)
 - [See a build that requires base image extension in order to succeed](/docs/extension-author-guide/create-extension/why-dockerfiles)
 - [Building blocks of an extension](/docs/extension-author-guide/create-extension/building-blocks-extension)
 - [Generating a build.Dockerfile for your application](/docs/extension-author-guide/create-extension/build-dockerfile)

content/docs/extension-author-guide/create-extension/build-dockerfile.md

@@ -7,25 +7,37 @@ weight=404
 
 #### detect
 
-* `cat $workspace/samples/extensions/tree/bin/detect` - the extension always detects (because its exit code is `0`) and provides a dependency
-  called `tree` by writing to the build plan.
+`cat $workspace/samples/extensions/tree/bin/detect` - the extension always detects (because its exit code is `0`) and provides a dependency
+  called `tree` by writing to the build plan
 
 #### generate
 
-* `cat extensions/tree/bin/generate` - the extension generates a `build.Dockerfile` that installs `tree` on the builder
+`cat extensions/tree/bin/generate` - the extension generates a `build.Dockerfile` that installs `tree` on the builder
   image
 
 ### Re-create our builder with `hello-extensions` updated to require `tree`
 
-* Edit `$workspace/samples/buildpacks/hello-extensions/bin/detect` to uncomment the first set of lines that
+1. Edit `$workspace/samples/buildpacks/hello-extensions/bin/detect` to uncomment the first set of lines that
   output `[[requires]]` to the build plan
-* `$workspace/pack/out/pack builder create $registry_namespace/extensions-builder --config $workspace/samples/builders/alpine/builder.toml --publish`
 
-### See a build in action (run failure case)
+2. Create the builder:
 
-* Build the application
-  image: `$workspace/pack/out/pack build hello-extensions --builder $registry_namespace/extensions-builder --lifecycle-image $LIFECYCLE_IMAGE --verbose`
-  - you should see:
+```
+$workspace/pack/out/pack builder create $registry_namespace/extensions-builder \
+  --config $workspace/samples/builders/alpine/builder.toml \
+  --publish
+```
+
+### Build the application image
+
+```
+$workspace/pack/out/pack build hello-extensions \
+  --builder $registry_namespace/extensions-builder \
+  --lifecycle-image $LIFECYCLE_IMAGE \
+  --verbose
+```
+
+You should see:
 
 ```
 [detector] ======== Results ========
@@ -46,10 +58,20 @@ weight=404
 Successfully built image hello-extensions
 ```
 
-* See the image fail to run: `docker run hello-extensions` - you should
-  see `ERROR: failed to launch: path lookup: exec: "curl": executable file not found in $PATH`.
-* What happened: our builder uses run image `cnbs/sample-stack-run:alpine` which does not have `curl` installed, so our
-  process failed to launch
+### See the image fail to run
+
+`docker run hello-extensions`
+
+You should see:
+
+```
+ERROR: failed to launch: path lookup: exec: "curl": executable file not found in $PATH
+```
+
+What happened: our builder uses run image `cnbs/sample-stack-run:alpine` which does not have `curl` installed, so our
+  process failed to launch.
+
+Let's take a look at how the `samples/curl` extension fixes the error by switching the run image to another image...
 
 <!--+ if false+-->
 ---

content/docs/extension-author-guide/create-extension/building-blocks-extension.md

@@ -5,7 +5,7 @@ weight=403
 
 ### Examine `tree` extension
 
-* `tree $workspace/samples/extensions/tree`
+`tree $workspace/samples/extensions/tree`
 
 You should see something akin to the following:
 

content/docs/extension-author-guide/create-extension/run-dockerfile.md

@@ -7,32 +7,51 @@ weight=405
 
 #### detect
 
-* `cat $workspace/samples/extensions/curl/bin/detect` - the extension always detects and provides a dependency
+`cat $workspace/samples/extensions/curl/bin/detect` - the extension always detects and provides a dependency
   called `curl`
 
 #### generate
 
-* `cat extensions/curl/bin/generate` - the extension generates a `run.Dockerfile` that switches the run image to
+`cat extensions/curl/bin/generate` - the extension generates a `run.Dockerfile` that switches the run image to
   reference `run-image-curl`
 
 ### Build a run image for `curl` extension to use
 
-* `cat $workspace/samples/stacks/alpine/run/curl.Dockerfile` - this is a simple Dockerfile that creates a CNB run image
-  from the `curl` base image by adding the required CNB user configuration and `io.buildpacks.stack.id` label; the
-  Dockerfile could come from anywhere, but we include it in the `stacks` directory for convenience
-* `docker build --tag run-image-curl --file $workspace/samples/stacks/alpine/run/curl.Dockerfile .`
+1. `cat $workspace/samples/stacks/alpine/run/curl.Dockerfile` - this is a simple Dockerfile that creates a CNB run image
+  from the `curl` base image by adding the required CNB user configuration and `io.buildpacks.stack.id` label
+   * The Dockerfile could come from anywhere, but we include it in the `stacks` directory for convenience
+
+2. Build the image:
+
+```
+docker build \
+  --file $workspace/samples/stacks/alpine/run/curl.Dockerfile \
+  --tag run-image-curl .
+```
 
 ### Re-create our builder with `hello-extensions` updated to require `curl`
 
-* Edit `$workspace/samples/buildpacks/hello-extensions/bin/detect` to uncomment the second set of lines that
+1. Edit `$workspace/samples/buildpacks/hello-extensions/bin/detect` to uncomment the second set of lines that
   output `[[requires]]` to the build plan
-* `$workspace/pack/out/pack builder create $registry_namespace/extensions-builder --config $workspace/samples/builders/alpine/builder.toml --publish`
 
-### See a build in action (success case)
+2. Create the builder:
 
-* Build the application
-  image: `$workspace/pack/out/pack build hello-extensions --builder $registry_namespace/extensions-builder --lifecycle-image $LIFECYCLE_IMAGE --verbose`
-  - you should see:
+```
+$workspace/pack/out/pack builder create $registry_namespace/extensions-builder \
+  --config $workspace/samples/builders/alpine/builder.toml \
+  --publish
+```
+
+### Build the application image
+
+```
+$workspace/pack/out/pack build hello-extensions \
+  --builder $registry_namespace/extensions-builder \
+  --lifecycle-image $LIFECYCLE_IMAGE \
+  --verbose
+```
+
+You should see:
 
 ```
 [detector] ======== Results ========
@@ -60,12 +79,20 @@ weight=405
 Successfully built image hello-extensions
 ```
 
-* See the image run successfully: `docker run hello-extensions` - you should see something akin
-  to `curl 7.85.0-DEV (x86_64-pc-linux-musl)`
-* What happened: now that `hello-extensions` requires both `tree` and `curl` in its build plan, both extensions are
+### See the image run successfully
+
+`docker run hello-extensions`
+
+You should see something akin to:
+
+```
+curl 7.85.0-DEV (x86_64-pc-linux-musl)
+```
+
+What happened: now that `hello-extensions` requires both `tree` and `curl` in its build plan, both extensions are
   included in the build and provide the needed dependencies for build and launch, respectively
-  * The `tree` extension installs `tree` at build time, as before
-  * The `curl` extension switches the run image to `run-image-curl`, which has `curl` installed. Now our `curl` process
+* The `tree` extension installs `tree` at build time, as before
+* The `curl` extension switches the run image to `run-image-curl`, which has `curl` installed. Now our `curl` process
     can succeed!
 
 ## What's next?

content/docs/extension-author-guide/create-extension/setup-local-environment.md

@@ -8,7 +8,7 @@ the builder image, and switches the run image to an image that has `curl` instal
 
 ### Ensure Docker is running
 
-* `docker version`
+`docker version`
 
 If you see output similar to the following, you're good to go! Otherwise, start Docker and check again.
 
@@ -36,22 +36,29 @@ Server: Docker Engine - Community
 
 ### Setup workspace directory
 
-* `workspace=<your preferred workspace directory>`
+`workspace=<your preferred workspace directory>`
 
 ### Clone the pack repo and build it (FIXME: remove when pack with extensions-phase-2 support is released)
 
-* `cd $workspace`
-* `git clone [email protected]:buildpacks/pack.git`
-* `cd pack`
-* `git checkout extensions-phase-2`
-* `make clean build`
+`cd $workspace`
+
+`git clone [email protected]:buildpacks/pack.git`
+
+`cd pack`
+
+`git checkout extensions-phase-2`
+
+`make clean build`
 
 ### Clone the samples repo
 
-* `cd $workspace`
-* `git clone https://github.com/buildpacks/samples.git`
-* `cd samples`
-* `git checkout extensions-phase-2` (FIXME: remove when `extensions-phase-2` merged)
+`cd $workspace`
+
+`git clone https://github.com/buildpacks/samples.git`
+
+`cd samples`
+
+`git checkout extensions-phase-2` (FIXME: remove when `extensions-phase-2` merged)
 
 <!--+ if false +-->
 ---

content/docs/extension-author-guide/create-extension/why-dockerfiles.md

@@ -9,41 +9,60 @@ Let's see a build that requires base image extension in order to succeed.
 
 #### detect
 
-* `cat $workspace/samples/buildpacks/hello-extensions/bin/detect` - the buildpack always detects but doesn't require any
-  dependencies (as the output build plan is empty)
+`cat $workspace/samples/buildpacks/hello-extensions/bin/detect` - the buildpack always detects but doesn't require any
+dependencies (as the output build plan is empty)
 
 #### build
 
-* `cat $workspace/samples/buildpacks/hello-extensions/bin/build` - the buildpack tries to use `tree` during the build
-  phase, and defines a launch process called `curl` that runs `curl --version` at runtime
+`cat $workspace/samples/buildpacks/hello-extensions/bin/build` - the buildpack tries to use `tree` during the build
+phase, and defines a launch process called `curl` that runs `curl --version` at runtime
 
 ### Create a builder with extensions and publish it
 
-* Ensure experimental features are enabled: `$workspace/pack/out/pack config experimental true`
-* Download the latest lifecycle tarball from the GitHub release
-  page: https://github.com/buildpacks/lifecycle/releases/tag/v0.15.0-rc.1 (FIXME: update to 0.15.0 when released)
-* Edit `$workspace/samples/builders/alpine/builder.toml` to add the following at the end of the file:
+1. Ensure experimental features are enabled: `$workspace/pack/out/pack config experimental true`
+
+2. Download the latest lifecycle tarball from the GitHub release
+   page: https://github.com/buildpacks/lifecycle/releases/tag/v0.15.0-rc.1 (FIXME: update to 0.15.0 when released)
+
+3. Edit `$workspace/samples/builders/alpine/builder.toml` to add the following at the end of the file:
 
 ```
 [lifecycle]
 uri = <path to lifecycle tarball in previous step>
 ```
 
-* Ensure you are authenticated with an OCI registry: `docker login` should succeed
-* Set your preferred registry namespace: `registry_namespace=<your preferred registry namespace>`
-  * For now, it is necessary for the builder to be pushed to a registry for `pack build` with image extensions to
-    succeed
-* `$workspace/pack/out/pack builder create $registry_namespace/extensions-builder --config $workspace/samples/builders/alpine/builder.toml --publish`
+4. Ensure you are authenticated with an OCI registry: `docker login` should succeed
+
+5. Set your preferred registry namespace: `registry_namespace=<your preferred registry namespace>`
+  * For now, it is necessary for the builder to be pushed to a registry for builds with image extensions to succeed
+
+6. Create the builder:
+
+```
+$workspace/pack/out/pack builder create $registry_namespace/extensions-builder \
+  --config $workspace/samples/builders/alpine/builder.toml \
+  --publish
+```
 
 ### See a build in action (build failure case)
 
-* Ensure experimental features are enabled: `$workspace/pack/out/pack config experimental true`
-* Set the lifecycle image for `pack` to use in the untrusted builder workflow (as the trusted workflow that uses
-  the `creator` is not currently supported): `LIFECYCLE_IMAGE=buildpacksio/lifecycle:0.15.0-rc.1` (FIXME: update to
-  0.15.0 when released)
-* Build the application image (note that the "source" directory is effectively ignored in our
-  example): `$workspace/pack/out/pack build hello-extensions --builder $registry_namespace/extensions-builder --lifecycle-image $LIFECYCLE_IMAGE --verbose --pull-policy always`
-  - you should see:
+1. Ensure experimental features are enabled: `$workspace/pack/out/pack config experimental true`
+
+2. Set the lifecycle image for `pack` to use in the untrusted builder workflow (as the trusted workflow that uses
+   the `creator` is not currently supported): `LIFECYCLE_IMAGE=buildpacksio/lifecycle:0.15.0-rc.1` (FIXME: update to
+   0.15.0 when released)
+
+3. Build the application image (note that the "source" directory is effectively ignored in our example):
+
+```
+$workspace/pack/out/pack build hello-extensions \
+  --builder $registry_namespace/extensions-builder \
+  --lifecycle-image $LIFECYCLE_IMAGE \
+  --pull-policy always \
+  --verbose
+```
+
+You should see:
 
 ```
 [detector] ======== Results ========
@@ -60,11 +79,14 @@ uri = <path to lifecycle tarball in previous step>
 [extender] ERROR: failed to build: exit status 127
 ```
 
-* What happened: our builder doesn't have `tree` installed, so the `hello-extensions` buildpack failed to build (as it
-  tries to run `tree --version` in its `./bin/build` script). Even though there is a `samples/tree` extension that
-  passed detection (`pass: samples/[email protected]`), because the `hello-extensions` buildpack didn't require `tree` in the
-  build plan, the extension was omitted from the detected group (`skip: samples/[email protected] provides unused tree`). Let's
-  take a look at what the `samples/tree` extension does...
+What happened: our builder doesn't have `tree` installed, so the `hello-extensions` buildpack failed to build (as it
+tries to run `tree --version` in its `./bin/build` script).
+
+* Even though there is a `samples/tree` extension that passed detection (`pass: samples/[email protected]`), because
+  the `hello-extensions` buildpack didn't require `tree` in the build plan, the extension was omitted from the detected
+  group (`skip: samples/[email protected] provides unused tree`).
+
+Let's take a look at how the `samples/tree` extension installs `tree` on the builder image...
 
 <!--+ if false+-->
 ---