Restructured the layout of the current documentation

content/en/docs/developer-guides/_index.md

@@ -0,0 +1,5 @@
+---
+title: Developer documentation
+description: This documentation covers best practices for developing plugins for Notation
+weight: 5
+---

content/en/docs/concepts/secure-plugin-development.md → content/en/docs/developer-guides/secure-plugin-development.md

@@ -2,7 +2,7 @@
 title: "Securely develop plugins for Notation"
 description: "Best practices for securely developing and distributing plugins for Notation"
 type: docs
-weight: 2
+weight: 1
 ---
 
 {{% alert title="Important" color="important" %}}

content/en/docs/faq.md

@@ -1,13 +1,13 @@
 ---
 title: "Frequently asked questions"
-description: "Frequently asked questions about Notary"
+description: "Frequently asked questions about Notary Project"
 type: docs
-weight: 8
+weight: 7
 ---
 
-## What registries are compatible with Notary?
+## What registries are compatible with Notation?
 
-The following registries are compatible with Notary for artifact signing and verification:
+The following registries are compatible with Notation for artifact signing and verification:
 
 - [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/?wt.mc_id=azurelearn_inproduct_oss_notaryproject)
 - [Amazon Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)
@@ -18,25 +18,25 @@ The following registries are compatible with Notary for artifact signing and ver
 
 ## JWS signature envelope
 
-**Q: Why JWT is not used as the signature envelope format?**
+**Q: Why is JWT not used as the signature envelope format?**
 
-**A:** JWT uses JWS compact serialization which do not support unsigned attributes. Notary signature requires support for unsigned attributes. Instead we use the *JWS JSON Serialization* representation, which supports unsigned attributes.
+**A:** JWT uses JWS compact serialization which do not support unsigned attributes. Notary Project signature requires support for unsigned attributes. Instead we use the *JWS JSON Serialization* representation, which supports unsigned attributes.
 
 **Q: Why JWT `exp` and `iat` claims are not used?**
 
-**A:** Unlike JWT which always contains a JSON payload, Notary envelope can support payloads other than JSON, like binary. Reusing the JWT payload structure and claims, limits the Notary JWS envelope to only support JSON payload, which is undesirable. Also, reusing JWT claims requires following same claim semantics as defined in JWT specifications. The [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) claim requires that verifier MUST reject the signature if current time equals or is greater than `exp`, where as Notary allows verification policy to define how expiry is handled.
+**A:** Unlike JWT which always contains a JSON payload, the Notary Project signature envelope can support payloads other than JSON, like binary. Reusing the JWT payload structure and claims, limits the Notary Project signature JWS envelope to only support JSON payload, which is undesirable. Also, reusing JWT claims requires following the same claim semantics as defined in JWT specifications. The [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) claim requires that the verifier MUST reject the signature if the current time equals or is greater than `exp`, where as Notation allows verification policy to define how expiry is handled.
 
 ## Signature specification
 
-**Q: How will Notary support multiple signature envelope formats?**
+**Q: How will Notation support multiple signature envelope formats?**
 
 **A:** The `mediaType` of artifact manifest's blob identifies the signature envelope type.  
 The client implementation can use the aforementioned `mediaType` to parse the signature envelope.
 
-**Q: How will Notary support multiple payload formats?**
+**Q: How will Notation support multiple payload formats?**
 
 **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats.
-For [JWS JSON serialization](https://github.com/notaryproject/notaryproject/blob/main/specs/signature-envelope-jws.md) signature envelope, versioning is achieved by the `cty` field in ProtectedHeaders.
+For [JWS JSON serialization](https://github.com/notaryproject/specifications/blob/main/specs/signature-envelope-jws.md) signature envelope, versioning is achieved by the `cty` field in ProtectedHeaders.
 
 
 ## Signature scheme
@@ -56,12 +56,12 @@ This has implication such as an end user with CA issued certificate can masquera
 
 ## Trust store and trust policy
 
-**Q: Does Notary supports `n` out of `m` signatures verification requirement?**
+**Q: Does Notation supports `n` out of `m` signatures verification requirement?**
 
-**A:** Notary doesn't support n out m signature requirement verification scheme.
+**A:** Notation doesn't support `n` out of `m` signature requirement verification scheme.
 Signature verification workflow succeeds if verification succeeds for at least one signature.
 
-**Q: Does Notary support overriding of revocation endpoints to support signature verification in disconnected environments?**
+**Q: Does Notation support overriding of revocation endpoints to support signature verification in disconnected environments?**
 
 **A:** TODO: Update after verification extensibility spec is ready.
 Not natively supported but a user can configure `revocationValidations` to `skip` and then use extended validations to check for revocation.

content/en/docs/glossary.md

@@ -1,7 +1,7 @@
 ---
 title: Glossary
 description: A list of Notary Project's terminologies 
-weight: 11
+weight: 8
 ---
 ## Notary Project 
 The Notary Project refers to the [GitHub organization](https://github.com/notaryproject), the community, all specifications, and all the repositories under the GitHub organization, including community-released tools like [notary](https://github.com/notaryproject/notary) and [notation](https://github.com/notaryproject/notation).

content/en/docs/notary-specification.md

@@ -0,0 +1,8 @@
+---
+title: "Notary Project specifications and requirements"
+description: "Notary Project specifications and requirements"
+type: docs
+weight: 6
+---
+
+More information on the Specifications, requirements, and other details about the Notary Project can be found in the [Specification repository](https://github.com/notaryproject/specifications/tree/main).

content/en/docs/quickstart-guides/_index.md

@@ -0,0 +1,5 @@
+---
+title: Quickstart guides
+description: The collection of guides for signing and verifying artifacts using Notation
+weight: 3
+---

content/en/docs/quickstart.md → content/en/docs/quickstart-guides/quickstart.md

@@ -2,7 +2,7 @@
 title: "Quickstart: Sign and validate a container image"
 description: "Quickly set up a OCI-based registry and use notation to sign and validate a container image"
 type: docs
-weight: 2
+weight: 1
 ---
 
 {{% alert title="Playground" color="info" %}}
@@ -14,7 +14,7 @@ You can also follow this guide on online remote cloud interactive playground on
 Before you begin, you need:
 
 * Docker installed and running, such as [Docker desktop](https://www.docker.com/products/docker-desktop/).
-* [Notation CLI]({{< ref "/docs/installation/cli" >}}) installed and configured.
+* [Notation CLI]({{< ref "/docs/user-guides/installation/cli" >}}) installed and configured.
 
 ## Create an OCI-compatible registry
 
@@ -28,7 +28,7 @@ docker run -d -p 5001:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name regist
 If the host port 5001 is already in use, you can use another host port. 
 {{% /alert %}}
 
-If you want to use Notation with other registries, refer to [which registries are compatible with Notary]({{< ref "/docs/faq#what-registries-are-compatible-with-notary" >}}) for more alternatives. See [Authenticate with OCI-compliant registries]({{< ref "/docs/how-to/registry-authentication" >}}) when you log in to another OCI registry.
+If you want to use Notation with other registries, refer to [which registries are compatible with Notary]({{< ref "/docs/faq#what-registries-are-compatible-with-notary" >}}) for more alternatives. See [Authenticate with OCI-compliant registries]({{< ref "/docs/user-guides/how-to/registry-authentication" >}}) when you log in to another OCI registry.
 
 ## Add an image to the OCI-compatible registry
 
@@ -77,7 +77,7 @@ notation cert generate-test --default "wabbit-networks.io"
 ```
 
 {{% alert title="Note" color="primary" %}}
-At this time, test key and self-signed certificate files created using `notation cert generate-test` can't be removed using only `notation key delete` and `notation cert delete`. For more details on fully removing the test key and self-signed certificate files, see [Remove the test key and self-signed certificate]({{< ref "/docs/installation/uninstall#remove-the-test-key-and-self-signed-certificate" >}}).
+At this time, test key and self-signed certificate files created using `notation cert generate-test` can't be removed using only `notation key delete` and `notation cert delete`. For more details on fully removing the test key and self-signed certificate files, see [Remove the test key and self-signed certificate]({{< ref "/docs/user-guides/installation/uninstall#remove-the-test-key-and-self-signed-certificate" >}}).
 {{% /alert %}}
 
 Use `notation key ls` to confirm the signing key is correctly configured. Key name with a `*` prefix is the default key.
@@ -125,7 +125,7 @@ localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda27
 
 ## Create a trust policy
 
-To verify the container image, configure the trust policy to specify trusted identities that sign the artifacts, and level of signature verification to use. For more details, see [trust policy spec](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-policy).
+To verify the container image, configure the trust policy to specify trusted identities that sign the artifacts, and level of signature verification to use. For more details, see [trust policy spec](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#trust-policy).
 
 Create a JSON file with the following trust policy, for example:
 
@@ -162,7 +162,7 @@ Use `notation policy show` to view the applied policy configuration. For example
 notation policy show
 ```
 
-The above JSON creates a trust policy named `wabbit-networks-images`. The policy has `registryScopes` set to `*`, which applies the policy to all the artifacts of any registry. The `signatureVerification` is set to `strict`, which checks all validations and any failure will fail the signature verification. This policy uses the `wabbit-networks.io` trust store of type `ca` which was created in the previous step. For more details on trust policies, see [trust policy spec](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-policy).
+The above JSON creates a trust policy named `wabbit-networks-images`. The policy has `registryScopes` set to `*`, which applies the policy to all the artifacts of any registry. The `signatureVerification` is set to `strict`, which checks all validations and any failure will fail the signature verification. This policy uses the `wabbit-networks.io` trust store of type `ca` which was created in the previous step. For more details on trust policies, see [trust policy spec](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#trust-policy).
 
 To enable trust policy for specific repositories, set the `registryScopes` to those specific repositories. For example:
 
@@ -192,4 +192,4 @@ To remove the sample registry running on your development computer:
 docker rm -f registry
 ```
 
-To reset your `notation` configuration, remove the notation configuration directory. For more details, see [Remove the configuration files]({{< ref "/docs/installation/uninstall" >}}).
+To reset your `notation` configuration, remove the notation configuration directory. For more details, see [Remove the configuration files]({{< ref "/docs/user-guides/installation/uninstall" >}}).

content/en/docs/user-guides/_index.md

@@ -0,0 +1,5 @@
+---
+title: User guides
+description: The collection of guides for Notation users
+weight: 4
+---

content/en/docs/cli-reference/_index.md → content/en/docs/user-guides/cli-reference/_index.md

@@ -1,5 +1,5 @@
 ---
 title: CLI Reference
 description: Reference documentation for notation
-weight: 10
+weight: 4
 ---

content/en/docs/concepts/experimental-features.md → content/en/docs/user-guides/experimental-features.md

@@ -2,14 +2,14 @@
 title: "Experimental features"
 description: "Explanation of experimental features"
 type: docs
-weight: 10
+weight: 6
 ---
 
 Starting in version `v1.0.0-rc.4`, Notation began introducing experimental features. Experimental features are features that are not yet ready for production use but are available for testing and evaluation. Experimental features may change significantly in later releases or be completely removed. Experimental features are not enabled by default and are not supported.
 
 Currently, Notation has the following experimental features:
 
-- [Signing, listing and verifying images as OCI image layout]({{< ref "/docs/how-to/oci-image-layout" >}})
+- [Signing, listing and verifying images as OCI image layout]({{< ref "/docs/user-guides/how-to/oci-image-layout" >}})
 - Store signatures using artifact manifest (requires registry support). Deprecated in `v1.0.0-rc.5`.
 - Use [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc2/spec.md#enabling-the-referrers-api)
 

content/en/docs/how-to/_index.md → content/en/docs/user-guides/how-to/_index.md

@@ -1,6 +1,6 @@
 ---
 title: How-to guides
-description: The collection of guides for configuring and using Notary
-weight: 5
+description: The collection of guides for configuring and using Notation
+weight: 3
 ---
 

content/en/docs/how-to/manage-signatures.md → content/en/docs/user-guides/how-to/manage-signatures.md

@@ -2,11 +2,11 @@
 title: "Manage signatures"
 description: "How to list, inspect, and delete a signature on an artifact"
 type: docs
-weight: 10
+weight: 6
 ---
 
 {{% alert title="Important" color="important" %}}
-When managing signatures on artifacts in remote repositories that require authentication, you must authenticate using `notation login` before you can manage signatures on artifacts in those repositories. For more information, see [Authenticate to a remote repository]({{< ref "/docs/how-to/registry-authentication" >}}).
+When managing signatures on artifacts in remote repositories that require authentication, you must authenticate using `notation login` before you can manage signatures on artifacts in those repositories. For more information, see [Authenticate to a remote repository]({{< ref "/docs/user-guides/how-to/registry-authentication" >}}).
 {{% /alert %}}
 
 ## List signatures on an artifact

content/en/docs/how-to/manage-trust-policy.md → content/en/docs/user-guides/how-to/manage-trust-policy.md

@@ -5,7 +5,7 @@ type: docs
 weight: 2
 ---
 
-By default, `notation` configures and manages a trust policy in the [configuration directory]({{< ref "/docs/concepts/directory-structure" >}}). You can directly change the trust policy file in that directory to manage your trust policies. 
+By default, `notation` configures and manages a trust policy in the [configuration directory]({{< ref "/docs/user-guides/how-to/notary-project-concepts.md" >}}). You can directly change the trust policy file in that directory to manage your trust policies. 
 
 Alternatively, you can manage trust policies using the `notation policy import` and `notation policy show` commands. These commands have the following benefits over directly editing the default trust policy file:
 

content/en/docs/concepts/directory-structure.md → content/en/docs/user-guides/how-to/notary-project-concepts.md

@@ -2,7 +2,7 @@
 title: "Notation directory structure for system configuration"
 description: "How to configure the directory structure"
 type: docs
-weight: 1
+weight: 7
 ---
 
 Notation CLI requires local file systems support for the following components. They should be stored in different places per different operating system.

content/en/docs/how-to/notation-config-file.md → content/en/docs/user-guides/how-to/notation-config-file.md

@@ -2,7 +2,7 @@
 title: "Customize the Notation configuration file"
 description: "How to customize Notation configuration in different OS platforms"
 type: docs
-weight: 4
+weight: 3
 ---
 
 This guide demonstrates how to customize the Notation system configuration in `config.json` and signing key in `signingkeys.json` respectively. By default, you don't need to create or modify them since Notation has default system settings and signing key configuration unless you want to customize them.
@@ -12,7 +12,7 @@ This guide demonstrates how to customize the Notation system configuration in `c
 The configuration file `config.json` location is different per operating system. `signingkeys.json` will be generated and stored in the same directory with `config.json`. You can use the Notation CLI or libraries to alter locations through the `XDG_CONFIG_HOME` environment variable.
 
 {{% alert title="Note" color="primary" %}}
-You can find the details of Notation directory structure for system configuration in this [guide]({{< ref "/docs/concepts/directory-structure" >}}).
+You can find the details of Notation directory structure for system configuration in this [guide]({{< ref "/docs/user-guides/how-to/notary-project-concepts.md" >}}).
 {{% /alert %}}
 
 ### Linux

content/en/docs/how-to/oci-image-layout.md → content/en/docs/user-guides/how-to/oci-image-layout.md

@@ -1,12 +1,10 @@
 ---
 title: Manage images as OCI image layout
 description: Build, sign, push, and verify images as OCI image layout
-weight: 10
+weight: 5
 ---
 
-OCI image layout is a directory structure that contains files and folders that refer to an OCI image. OCI image layout is defined in [OCI image spec](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md).
-
-When you sign an image after it is pushed to a registry, it is possible that you are not signing the correct image. You also may not be certain that the image hasn't been altered. Using OCI image layout, you can sign images on local disk before pushing them to the remote registry. Signing an image before you push it a registry provides helps ensure you are signing the correct image, and consumers of that image can verify that same image.
+OCI image layout is a directory structure that contains files and folders that refer to an OCI image. OCI image layout is defined in [OCI image spec](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md). Using OCI image layout, you can sign images on local disk before pushing them to the remote registry. 
 
 {{% alert title="Important" color="primary" %}}
 This feature is experimental. It is not recommended for production use.