WIP redesign notes and admonitions

This brings the initial work to redesign our notes and admonitions. The following adminitions are supported: - info: generic note with "info" icon - tip: note with a "lightbulb" icon - check: note with a "check" icon - important: note with an exclamation mark - warning: note with an exclamation mark in a triangle Things remaining: - update the examples and descriptions in "test.md" - tweak line-heights / typography - review uses of "warning" versus "important"; their purpose needs to be defined better (and styled accordingly) - color-schemes: we can likely use the same colors for "dark" and "light" mode. There's also some colors ("warning", e.g.) that use some tweaking. - add classes to existing notes to switch between a "regular" note to notes with an icon ("admonition"). - removing "note" as first line: when using an icon, the icon can replace "note" in many cases; removing the "note" makes the note more compact without loosing meaning, so we should remove those. - for other notes, we should do the reverse: replace "note" with a more suitable introduction. I updated some pages to illustrate this. Setting a more descriptive first line can give notes a better context. Signed-off-by: Sebastiaan van Stijn <[email protected]>
docker · Jul 7, 2021 · fefd8e4 · fefd8e4
1 parent 3ccabce
commit fefd8e4
Show file tree

Hide file tree

Showing 10 changed files with 100 additions and 81 deletions.
diff --git a/_includes/install-script.md b/_includes/install-script.md
@@ -64,6 +64,7 @@ As the message indicates, non-root users cannot run Docker commands by default.
 > Docker can also be installed without `root` privileges, or configured to run
 > in rootless mode. For instructions on running Docker in rootless mode, refer to
 > [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).
+{:.tip}
 
 #### Install pre-releases
 

diff --git a/_scss/_night-mode.scss b/_scss/_night-mode.scss
@@ -69,16 +69,10 @@ body.night {
         border: 1px solid #192837;
     }
     blockquote {
-        color: $note-color-night;
         background: $note-bg-color-night;
-        &.warning, &.warning p:first-child {
-            color: $warning-color-night !important;
-        }
-        &.important {
-            border-left-color: #f5ac45 !important;
-        }
-        &.important, &.important p:first-child {
-            color: $important-color-night !important;
+
+        &::before {
+          color: $note-icon-color-night;
         }
     }
     table {

diff --git a/_scss/_notes.scss b/_scss/_notes.scss
@@ -1,53 +1,59 @@
 //noinspection CssNoGenericFontName
 blockquote {
-  background-color:  $note-bg-color;
-  border-left-color: $note-color;
-  font-size:         unset; // override bootstrap font-size for blockquotes
+  background-color: $note-bg-color;
+  border-left:      5px solid $note-color;
+  font-size:        unset; // override bootstrap font-size for blockquotes
 
+  // Use relative position to allow the optional icon (::before) to be positioned.
+  // Also set a min-height to reserve height for the icon to fit.
+  position:         relative;
+  min-height:       50px;
+
+  // The ::before is used for the icon in admonitions. By default, no icon is
+  // present (content: none), and these rules do not have an effect.
+  &::before {
+    font-family: FontAwesome;
+    font-size:   24px;
+    line-height: 50px;
+    text-align:  center;
+    color:       $note-icon-color;
+    display:     inline-block;
+    position:    absolute;
+    top:         0;
+    bottom:      0;
+    content:     none; // default note has no icon
+  }
+
+  // Vertically align first line with icon (if present) and make first line bold
   > p:first-child {
-    color:       $note-color;
     font-weight: 700;
     margin-top:  0;
-
-    &::before {
-      font-family: FontAwesome;
-      content:     "\f058 \00a0";
-    }
+    line-height: 30px;
   }
 
-  // Maintain backwards compatibility with old note style
+  // Maintain backwards compatibility with old, single-line, note style
   > p:only-child {
     color:       inherit;
     font-weight: inherit;
-
-    &::before {
-      content: none;
-    }
   }
 
-  &.important {
-    border-left-color: $important-color;
-
-    > p:first-child {
-      color: $important-color;
+  &.info, &.check, &.tip, &.important, &.warning {
+    border-radius: 5px 0 0 5px;
+    border-style:  solid;
+    border-width:  1px 1px 1px 50px;
 
-      &::before {
-        content: "\f06a  \00a0";
-      }
+    &::before {
+      width: 50px;
+      left: -50px;
     }
   }
 
-  &.warning {
-    border-left-color: $warning-color;
-
-    > p:first-child {
-      color: $warning-color;
 
-      &::before {
-        content: "\f057  \00a0";
-      }
-    }
-  }
+  &.info      { border-color: $note-color;         &::before{ content: "\f129"; }} // fa-info
+  &.check     { border-color: hsl(130, 100%, 32%); &::before{ content: "\f00c"; }} // fa-check
+  &.tip       { border-color: hsl( 44, 100%, 45%); &::before{ content: "\f0eb"; }} // fa-lightbulb
+  &.important { border-color: $important-color;    &::before{ content: "\f12a"; }} // fa-exclamation
+  &.warning   { border-color: $warning-color;      &::before{ content: "\f071"; }} // fa-exclamation-triangle
 }
 
 /* For Bootstrap badges */
@@ -64,16 +70,8 @@ span {
     vertical-align: baseline;
     white-space:    nowrap;
 
-    &.badge-info {
-      background-color: $note-color;
-    }
-
-    &.badge-danger {
-      background-color: $warning-color;
-    }
-
-    &.badge-warning {
-      background-color: $important-color;
-    }
+    &.badge-info    { background-color: $note-color; }
+    &.badge-danger  { background-color: $warning-color; }
+    &.badge-warning { background-color: $important-color; }
   }
 }
diff --git a/_scss/_variables.scss b/_scss/_variables.scss
@@ -30,8 +30,9 @@ $bg-component:            hsl(240,  14%,  99%);
 $bg-card:                 hsl(  0,   0%, 100%);
 
 // notes, warnings
-$note-color:              hsl(206,  82%,  43%);
 $note-bg-color:           hsl(206,  83%,  98%);
+$note-icon-color:         hsl(206,   0%, 100%);
+$note-color:              hsl(206,  82%,  43%);
 $important-color:         hsl( 35,  91%,  35%);
 $warning-color:           hsl(  2,  58%,  54%);
 
@@ -59,8 +60,9 @@ $bg-component-night:      hsl(203,  44%,  10%);
 $bg-card-night:           hsl(203,  33%,   8%);
 
 // notes, warnings
-$note-color-night:        hsl(180,   1%,  83%);
 $note-bg-color-night:     hsl(203,  35%,  19%);
+$note-icon-color-night:   hsl(203,   0%, 100%);
+$note-color-night:        hsl(180,   1%,  83%);
 $important-color-night:   hsl( 35,  90%,  62%);
 $warning-color-night:     hsl(  2, 100%,  74%);
 

diff --git a/engine/install/binaries.md b/engine/install/binaries.md
@@ -9,9 +9,6 @@ redirect_from:
 - /installation/binaries/
 ---
 
-> **Note**: You may have been redirected to this page because there is no longer
-> a dynamically-linked Docker package for your Linux distribution.
-
 If you want to try Docker or use it in a testing environment, but you're not on
 a supported platform, you can try installing from static binaries. If possible,
 you should use packages built for your operating system, and use your operating

diff --git a/engine/install/centos.md b/engine/install/centos.md
@@ -134,12 +134,13 @@ $ sudo yum-config-manager \
     If prompted to accept the GPG key, verify that the fingerprint matches
     `060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35`, and if so, accept it.
 
-    > Got multiple Docker repositories?
+    > Got multiple Docker repositories enabled?
     >
     > If you have multiple Docker repositories enabled, installing
     > or updating without specifying a version in the `yum install` or
     > `yum update` command always installs the highest possible version,
     > which may not be appropriate for your stability needs.
+    {:.tip}
 
     Docker is installed but not started. The `docker` group is created, but no users are added to the group.
 

diff --git a/engine/install/debian.md b/engine/install/debian.md
@@ -71,6 +71,7 @@ from the repository.
 >
 > For Raspbian, installing using the repository is not yet supported. You must
 > instead use the [convenience script](#install-using-the-convenience-script).
+{:.important}
 
 #### Set up the repository
 
@@ -100,12 +101,16 @@ from the repository.
     **nightly** or **test** repository, add the word `nightly` or `test` (or both)
     after the word `stable` in the commands below. [Learn about **nightly** and **test** channels](index.md).
 
-    > **Note**: The `lsb_release -cs` sub-command below returns the name of your
-    > Debian distribution, such as `helium`. Sometimes, in a distribution
+    > **Other distributions**
+    >
+    > The `lsb_release -cs` sub-command below returns the name of your
+    > Debian distribution, such as `stretch`. Sometimes, in a distribution
     > like BunsenLabs Linux, you might need to change `$(lsb_release -cs)`
     > to your parent Debian distribution. For example, if you are using
-    >  `BunsenLabs Linux Helium`, you could use `stretch`. Docker does not offer any guarantees on untested
-    > and unsupported Debian distributions.
+    >  `BunsenLabs Linux Helium`, you could use `stretch`.
+    > Docker does not offer any guarantees on untested and unsupported Debian
+    > derivatives.
+    {:.important}
 
     <ul class="nav nav-tabs">
       <li class="active"><a data-toggle="tab" data-target="#x86_64_repo">x86_64 / amd64</a></li>
@@ -144,7 +149,8 @@ from the repository.
 
 #### Install Docker Engine
 
-This procedure works for Debian on `x86_64` / `amd64`, `armhf`, `arm64`, and Raspbian.
+> This procedure works for Debian on `x86_64` / `amd64`, `armhf`, `arm64`, and Raspbian.
+{:.note}
 
 1. Update the `apt` package index, and install the _latest version_ of Docker
    Engine and containerd, or go to the next step to install a specific version:
@@ -154,12 +160,13 @@ This procedure works for Debian on `x86_64` / `amd64`, `armhf`, `arm64`, and Ras
     $ sudo apt-get install docker-ce docker-ce-cli containerd.io
     ```
 
-    > Got multiple Docker repositories?
+    > Got multiple Docker repositories enabled?
     >
     > If you have multiple Docker repositories enabled, installing
     > or updating without specifying a version in the `apt-get install` or
     > `apt-get update` command always installs the highest possible version,
     > which may not be appropriate for your stability needs.
+    {:.tip}
 
 2.  To install a _specific version_ of Docker Engine, list the available versions
     in the repo, then select and install:
@@ -214,9 +221,12 @@ a new file each time you want to upgrade Docker.
     `armhf`, or `arm64`, and download the `.deb` file for the Docker Engine
     version you want to install.
 
-    > **Note**: To install a **nightly** or **test** (pre-release) package,
-    > change the word `stable` in the above URL to `nightly` or `test`.
-    > [Learn about **nightly** and **test** channels](index.md).
+    > Feeling adventurous?
+    >
+    > To install a **test** (pre-release) or **nightly** package,
+    > change the word `stable` in the above URL to `test` or `nightly`.
+    > [Learn about **test** and **nightly** channels](index.md).
+    {:.tip}
 
 2.  Install Docker Engine, changing the path below to the path where you downloaded
     the Docker package.

diff --git a/engine/install/fedora.md b/engine/install/fedora.md
@@ -122,12 +122,13 @@ $ sudo dnf config-manager \
     If prompted to accept the GPG key, verify that the fingerprint matches
     `060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35`, and if so, accept it.
 
-    > Got multiple Docker repositories?
+    > Got multiple Docker repositories enabled?
     >
     > If you have multiple Docker repositories enabled, installing
     > or updating without specifying a version in the `dnf install` or
     > `dnf update` command always installs the highest possible version,
     > which may not be appropriate for your stability needs.
+    {:.tip}
 
     Docker is installed but not started. The `docker` group is created, but no users are added to the group.
 

diff --git a/engine/install/ubuntu.md b/engine/install/ubuntu.md
@@ -118,12 +118,16 @@ from the repository.
     **nightly** or **test** repository, add the word `nightly` or `test` (or both)
     after the word `stable` in the commands below. [Learn about **nightly** and **test** channels](index.md).
 
-    > **Note**: The `lsb_release -cs` sub-command below returns the name of your
+    > **Other distributions**
+    >
+    > The `lsb_release -cs` sub-command below returns the name of your
     > Ubuntu distribution, such as `xenial`. Sometimes, in a distribution
     > like Linux Mint, you might need to change `$(lsb_release -cs)`
     > to your parent Ubuntu distribution. For example, if you are using
-    >  `Linux Mint Tessa`, you could use `bionic`. Docker does not offer any guarantees on untested
-    > and unsupported Ubuntu distributions.
+    >  `Linux Mint Tessa`, you could use `bionic`.
+    > Docker does not offer any guarantees on untested and unsupported Ubuntu
+    > derivatives.
+    {:.important}
 
     <ul class="nav nav-tabs">
       <li class="active"><a data-toggle="tab" data-target="#x86_64_repo">x86_64 / amd64</a></li>
@@ -170,12 +174,13 @@ from the repository.
     $ sudo apt-get install docker-ce docker-ce-cli containerd.io
     ```
 
-    > Got multiple Docker repositories?
+    > Got multiple Docker repositories enabled?
     >
     > If you have multiple Docker repositories enabled, installing
     > or updating without specifying a version in the `apt-get install` or
     > `apt-get update` command always installs the highest possible version,
     > which may not be appropriate for your stability needs.
+    {:.tip}
 
 2.  To install a _specific version_ of Docker Engine, list the available versions
     in the repo, then select and install:
@@ -230,9 +235,12 @@ a new file each time you want to upgrade Docker.
     `armhf`, or `arm64`, and download the `.deb` file for the Docker Engine
     version you want to install.
 
-    > **Note**: To install a **nightly** or **test** (pre-release) package,
-    > change the word `stable` in the above URL to `nightly` or `test`.
+    > Feeling adventurous?
+    >
+    > To install a **test** (pre-release) or **nightly** package,
+    > change the word `stable` in the above URL to `test` or `nightly`.
     > [Learn about **nightly** and **test** channels](index.md).
+    {:.tip}
 
 2.  Install Docker Engine, changing the path below to the path where you downloaded
     the Docker package.

diff --git a/engine/security/protect-access.md b/engine/security/protect-access.md
@@ -93,8 +93,9 @@ it only connects to servers with a certificate signed by that CA.
 
 ### Create a CA, server and client keys with OpenSSL
 
-> **Note**: Replace all instances of `$HOST` in the following example with the
+> Replace all instances of `$HOST` in the following example with the
 > DNS name of your Docker daemon's host.
+{:.tip}
 
 First, on the **Docker daemon's host machine**, generate CA private and public keys:
 
@@ -129,8 +130,9 @@ Now that you have a CA, you can create a server key and certificate
 signing request (CSR). Make sure that "Common Name" matches the hostname you use
 to connect to Docker:
 
-> **Note**: Replace all instances of `$HOST` in the following example with the
+> Replace all instances of `$HOST` in the following example with the
 > DNS name of your Docker daemon's host.
+{:.tip}
 
 ```console
 $ openssl genrsa -out server-key.pem 4096
@@ -177,8 +179,9 @@ Docker clients.
 For client authentication, create a client key and certificate signing
 request:
 
-> **Note**: For simplicity of the next couple of steps, you may perform this
+> For simplicity of the next couple of steps, you may perform this
 > step on the Docker daemon's host machine as well.
+{:.info}
 
 ```console
 $ openssl genrsa -out key.pem 4096
@@ -250,9 +253,11 @@ certificates and trusted CA:
 > This step should be run on your Docker client machine. As such, you
 > need to copy your CA certificate, your server certificate, and your client
 > certificate to that machine.
+{:.info}
 
-> **Note**: Replace all instances of `$HOST` in the following example with the
+> Replace all instances of `$HOST` in the following example with the
 > DNS name of your Docker daemon's host.
+{:.tip}
 
 ```console
 $ docker --tlsverify \
@@ -262,10 +267,12 @@ $ docker --tlsverify \
     -H=$HOST:2376 version
 ```
 
-> **Note**:
-> Docker over TLS should run on TCP port 2376.
+> While you can configure the Docker Engine API on any port, Docker over TLS
+> should run on TCP port 2376, which is [registered for this purpose](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=docker){: target="_blank" rel="noopener" class="_"}.
+{:.check}
 
-> **Warning**:
+> **Warning**
+>
 > As shown in the example above, you don't need to run the `docker` client
 > with `sudo` or the `docker` group when you use certificate authentication.
 > That means anyone with the keys can give any instructions to your Docker