Merge remote-tracking branch 'distribution_docs/migrate_distribution_…

…docs' into restore_docs3

Restore the documentation that was moved to https://github.com/docker/docker.github.io

 Conflicts:
	docs/compatibility.md
	docs/deploying.md
	docs/deprecated.md
	docs/garbage-collection.md
	docs/glossary.md
	docs/help.md
	docs/images/notifications.png
	docs/index.md
	docs/insecure.md
	docs/introduction.md
	docs/migration.md
	docs/notifications.md
	docs/recipes/apache.md
	docs/recipes/index.md
	docs/recipes/mirror.md
	docs/recipes/nginx.md
	docs/recipes/osx-setup-guide.md
	docs/recipes/osx/config.yml
	docs/storage-drivers/azure.md
	docs/storage-drivers/filesystem.md
	docs/storage-drivers/gcs.md
	docs/storage-drivers/index.md
	docs/storage-drivers/inmemory.md
	docs/storage-drivers/oss.md
	docs/storage-drivers/s3.md
	docs/storage-drivers/swift.md

docs/compatibility.md

@@ -1,84 +1,80 @@
-<!--[metadata]>
-+++
-title = "Compatibility"
-description = "describes get by digest pitfall"
-keywords = ["registry, manifest, images, tags, repository, distribution, digest"]
-[menu.main]
-parent="smn_registry_ref"
-weight=9
-+++
-<![end-metadata]-->
-
-# Registry Compatibility
+---
+description: describes get by digest pitfall
+keywords: registry, manifest, images, tags, repository, distribution, digest
+title: Registry compatibility
+---
+
+{% include registry.md %}
 
 ## Synopsis
-*If a manifest is pulled by _digest_ from a registry 2.3 with Docker Engine 1.9
+If a manifest is pulled by _digest_ from a registry 2.3 with Docker Engine 1.9
 and older, and the manifest was pushed with Docker Engine 1.10, a security check
-will cause the Engine to receive a manifest it cannot use and the pull will fail.*
+causes the Engine to receive a manifest it cannot use and the pull fails.
 
-## Registry Manifest Support
+## Registry manifest support
 
 Historically, the registry has supported a [single manifest type](./spec/manifest-v2-1.md)
 known as _Schema 1_.
 
-With the move toward multiple architecture images the distribution project
-introduced two new manifest types:  Schema 2 manifests and manifest lists.  The
-registry 2.3 supports all three manifest types and in order to be compatible
-with older Docker engines will, in certain cases, do an on-the-fly
-transformation of a manifest before serving the JSON in the response.
+With the move toward multiple architecture images, the distribution project
+introduced two new manifest types: Schema 2 manifests and manifest lists. Registry
+2.3 supports all three manifest types and sometimes performs an on-the-fly
+transformation of a manifest before serving the JSON in the response, to
+preserve compatibility with older versions of Docker Engine.
 
 This conversion has some implications for pulling manifests by digest and this
-document enumerate these implications.
+document enumerates these implications.
 
 
 ## Content Addressable Storage (CAS)
 
 Manifests are stored and retrieved in the registry by keying off a digest
-representing a hash of the contents.  One of the advantages provided by CAS is
-security: if the contents are changed, then the digest will no longer match.
+representing a hash of the contents. One of the advantages provided by CAS is
+security: if the contents are changed, then the digest no longer matches.
 This prevents any modification of the manifest by a MITM attack or an untrusted
 third party.
 
 When a manifest is stored by the registry, this digest is returned in the HTTP
-response headers and, if events are configured, delivered within the event.  The
+response headers and, if events are configured, delivered within the event. The
 manifest can either be retrieved by the tag, or this digest.
 
-For registry versions 2.2.1 and below, the registry will always store and
-serve _Schema 1_ manifests.  The Docker Engine 1.10 will first
-attempt to send a _Schema 2_ manifest, falling back to sending a
+For registry versions 2.2.1 and below, the registry always stores and
+serves _Schema 1_ manifests. Engine 1.10 first
+attempts to send a _Schema 2_ manifest, falling back to sending a
 Schema 1 type manifest when it detects that the registry does not
 support the new version.
 
 
 ## Registry v2.3
 
-### Manifest Push with Docker 1.9 and Older
-
-The Docker Engine will construct a _Schema 1_ manifest which the
-registry will persist to disk.
-
-When the manifest is pulled by digest or tag with any docker version, a
-_Schema 1_ manifest will be returned.
-
-### Manifest Push with Docker 1.10
+### Manifest push with Docker 1.10
 
-The docker engine will construct a _Schema 2_ manifest which the
-registry will persist to disk.
+The Engine constructs a _Schema 2_ manifest which the
+registry persists to disk.
 
 When the manifest is pulled by digest or tag with Docker Engine 1.10, a
-_Schema 2_ manifest will be returned.  The Docker Engine 1.10
+_Schema 2_ manifest is returned. Docker Engine 1.10
 understands the new manifest format.
 
 When the manifest is pulled by *tag* with Docker Engine 1.9 and older, the
 manifest is converted on-the-fly to _Schema 1_ and sent in the
-response.  The Docker Engine 1.9 is compatible with this older format.
+response. The Docker Engine 1.9 is compatible with this older format.
 
-*When the manifest is pulled by _digest_ with Docker Engine 1.9 and older, the
-same rewriting process will not happen in the registry.  If this were to happen
+When the manifest is pulled by _digest_ with Docker Engine 1.9 and older, the
+same rewriting process does not happen in the registry. If it did,
 the digest would no longer match the hash of the manifest and would violate the
-constraints of CAS.*
+constraints of CAS.
 
 For this reason if a manifest is pulled by _digest_ from a registry 2.3 with Docker
 Engine 1.9 and older, and the manifest was pushed with Docker Engine 1.10, a
-security check will cause the Engine to receive a manifest it cannot use and the
-pull will fail.
+security check causes the Engine to receive a manifest it cannot use and the
+pull fails.
+
+### Manifest push with Docker 1.9 and older
+
+The Docker Engine constructs a _Schema 1_ manifest which the
+registry persists to disk.
+
+When the manifest is pulled by digest or tag with any Docker version, a
+_Schema 1_ manifest is returned.
+