feat: add version control to documentation (#316)

Resolve #317. Add version
control to ORAS documentation. ORAS users will be able to choose a
version from the drop-down list.

v1.2.0 is the default version. `Next` is the upcoming version which is
in development.


![image](https://github.com/oras-project/oras-www/assets/40452856/b9de5563-c4ac-416e-bf99-cfe8cbf3f313)

---------

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>

docusaurus.config.js

@@ -53,12 +53,12 @@ const config = {
                     // Remove this to remove the "edit this page" links.
                     editUrl:
                         "https://github.com/oras-project/oras-www/tree/main/",
-                    lastVersion: "current",
-                    versions: {
-                        current: {
-                            label: "1.1.0",
-                        },
-                    },
+                        versions: {
+                            "1.1": {
+                                label: '1.1',
+                                path: '1.1',
+                            }
+                        }
                 },
                 blog: {
                     showReadingTime: true,
@@ -139,31 +139,31 @@ const config = {
             footer: {
                 style: "dark",
                 links: [
-                    {
-                        title: "Docs",
-                        items: [
-                            {
-                                label: "Introduction",
-                                to: "/docs/",
-                            },
-                            {
-                                label: "Installation",
-                                to: "/docs/installation",
-                            },
-                            {
-                                label: "How-to Guides",
-                                to: "/docs/how_to_guides/authentication",
-                            },
-                            {
-                                label: "ORAS Commands",
-                                to: "/docs/commands/use_oras_cli",
-                            },
-                            {
-                                label: "Client Libraries",
-                                to: "/docs/client_libraries/overview",
-                            },
-                        ],
-                    },
+                    // {
+                    //     title: "Docs",
+                    //     items: [
+                    //         {
+                    //             label: "Introduction",
+                    //             to: "/docs/",
+                    //         },
+                    //         {
+                    //             label: "Installation",
+                    //             to: "/docs/installation",
+                    //         },
+                    //         {
+                    //             label: "How-to Guides",
+                    //             to: "/docs/how_to_guides/authentication",
+                    //         },
+                    //         {
+                    //             label: "ORAS Commands",
+                    //             to: "/docs/commands/use_oras_cli",
+                    //         },
+                    //         {
+                    //             label: "Client Libraries",
+                    //             to: "/docs/client_libraries/overview",
+                    //         },
+                    //     ],
+                    // },
                     {
                         title: "Community",
                         items: [

versioned_docs/version-1.1/client_libraries/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Client Libraries",
+    "position": 40,
+    "link": {
+        "type": "generated-index",
+        "description": "The following languages are currently supported:"
+    }
+}

versioned_docs/version-1.1/client_libraries/go.mdx

@@ -0,0 +1,55 @@
+---
+title: Go
+sidebar_position: 1
+---
+
+# Go
+
+Source code: [github.com/oras-project/oras-go](https://github.com/oras-project/oras-go)
+
+## Introduction
+
+The ORAS Go client library provides the ability to replicate artifacts between different [Targets](./overview.mdx#target).  
+Furthermore, the version `v2` is a registry client conforming [image-spec v1.1.0-rc6](https://github.com/opencontainers/image-spec/releases/tag/v1.1.0-rc6) and [distribution-spec v1.1.0-rc4](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc4).
+
+Using the ORAS Go client library, you can develop your own registry client:
+
+```sh
+myclient push artifacts.example.com/myartifact:1.0 ./mything.thang
+```
+
+## Usage
+
+The package `oras.land/oras-go/v2` can quickly be imported in other Go-based tools that
+wish to benefit from the ability to store arbitrary content in container registries.
+
+1. Get the  `oras.land/oras-go/v2` package
+```sh
+go get oras.land/oras-go/v2
+```
+
+2. Import and use the `v2` package
+```go
+import "oras.land/oras-go/v2"
+```
+
+3. Run
+```sh
+go mod tidy
+```
+
+**The API documentation and examples are available at [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2).**
+
+## Quick Start
+
+### Push files to a remote repository
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PushFilesToRemoteRepository).
+
+### Pull files from a remote repository
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullFilesFromRemoteRepository).
+
+### Pull a docker or OCI image from a remote repository
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullImageFromRemoteRepository).
+
+### Pull an Image using the Docker credential store
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullImageUsingDockerCredentials).

versioned_docs/version-1.1/client_libraries/overview.mdx

@@ -0,0 +1,127 @@
+---
+title: Overview
+sidebar_position: 0
+---
+
+# Overview
+
+## Languages
+
+The following languages are currently supported:
+
+- [Go](./go.mdx)
+- [Python](https://oras-project.github.io/oras-py/getting_started/user-guide.html) 
+- [Rust](./rust.mdx) (in progress)
+
+## Unified Experience
+
+The objective of ORAS is simple as transferring artifacts from one place to another.
+
+In the conventional [client-server model](https://en.wikipedia.org/wiki/Client%E2%80%93server_model), the operation of downloading artifacts from the remote registries is referred to as **pull**, and the operation of uploading artifacts to the remote registry is referred to as **push**.
+
+This model can be generalized by abstracting the client and the server as **targets** so that pull and push can be viewed as **copying** from one target to another (see [**Copy API** oras-project/oras-go#8](https://github.com/oras-project/oras-go/pull/8)).
+For instances,
+
+- Copy from memory to a remote registry.
+- Copy from a remote registry to a local file folder.
+- Copy from a remote registry to another remote registry.
+- Copy from memory to a local file folder.
+
+### Targets
+
+Generally, a target is a [content-addressable storage (CAS)](https://en.wikipedia.org/wiki/Content-addressable_storage) with tags.
+All blobs in a CAS are addressed by their [descriptors](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/descriptor.md).
+
+To retrieve a blob,
+
+1. Get a descriptor. Optionally, it can be resolved by a tag.
+2. Query the blob with a descriptor.
+
+To store a blob,
+
+1. Store the blob directly in the CAS. A descriptor will be returned.
+2. Optionally, associate the returned descriptor with a tag.
+
+It is worth noting that a target is not equal to a registry.
+
+- Blobs can be tagged in a target but not in a registry.
+- Tag list is available in a registry but not always available in a target.
+
+### Graphs
+
+Besides plain blobs, it is natural to store [directed acyclic graphs (DAGs)](https://en.wikipedia.org/wiki/Directed_acyclic_graph) in a CAS.
+Precisely, all blobs are leaf nodes and most manifests are non-leaf nodes.
+
+An artifact is a rooted DAG where its root node is an [OCI manifest](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/manifest.md) or an [OCI Artifact Manifest](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md).
+Additionally, artifacts can be grouped by an [OCI index](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-index.md), which is also a rooted DAG.
+
+Given a node of a DAG in a CAS, it is efficient to find out all its children.
+Since CASs are usually not enumerable or indexed, it is not possible to find the parent nodes of an arbitrary node.
+Nevertheless, some CASs choose to implement or partially implement the functionality of parent node finding.
+For instances, registries with [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers) support are CASs with partially implementation where parent node finding is only available for manifest nodes.
+
+### Extended Copy
+
+With the concepts above, we can formally define that
+
+- **Copy** is a function to replicate a rooted DAG from one CAS to another.
+- **Extended Copy** is a function to replicate a DAG from one CAS to another.
+
+It is worth noting that extended copy is possible only if the source CAS supports parent node finding.
+Based on the scenarios, extended copy can have many options such as opting to copy a sub-DAG rooted by a certain node and all its parent nodes of a certain depth with / without their children.
+
+Optionally, node filters or even node modifiers can be attached to a copy process for advanced scenarios.
+
+Related issues:
+
+- [**Support copy of images and associated references** oras-project/oras-go#29](https://github.com/oras-project/oras-go/issues/29)
+- [**Copy Artifact Reference Graph** oras-project/oras#307](https://github.com/oras-project/oras/issues/307)
+
+Hint: A [polytree](https://en.wikipedia.org/wiki/Polytree) is a DAG.
+
+![polytree](./img/polytree.svg)
+
+## Paradigms
+
+🚧 *Note: this section is contingent on
+[oras-project/oras-go#8](https://github.com/oras-project/oras-go/pull/8) and
+does not reprersent the current state of the ORAS Go client library.*
+
+At a high-level, each client library provides the concept of a `Target` interface
+and a `Copy` method. `Copy` transfers content from one `Target` to another.
+
+### `Target`
+
+A `Target` represents a place to which one can send/push or retrieve/pull artifacts.
+Anything that implements this interface can be used as a place to send
+or retrieve artifacts.
+
+Some examples of a `Target` may include the following:
+
+- An OCI Registry
+- An [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md)
+- A local collection of files
+
+### `Copy`
+
+`Copy` copies a rooted DAG identified by a reference from one `Target` to another `Target`.
+
+#### Method signature
+
+The following is a rough method signature based on the Go version:
+
+```go
+func Copy(from Target, fromRef string, to Target, toRef string) Descriptor
+```
+
+### `ExtendedCopy`
+
+`Copy` copies a DAG reachable from a node identified by a reference from one `Target` to another `Target`.
+
+#### Method signature
+
+The following is a rough method signature based on the Go version:
+
+```go
+func ExtendedCopy(from Target, fromRef string, to Target, toRef string) Descriptor
+```