DOC-5052: Version labels and edition labels in body text (#70)

* Make sidebars black-on-white

* Create spans for edition and status

* Add label spans to preview

* Sidebar examples with and without titles

* Move inline label examples to their own section

* Parameterize label styles

* Create labels role for paragraph
to get labels with speech bubble tail

* Expand and clarify label examples

preview-src/index.adoc

@@ -2,6 +2,11 @@
 :doctype: book
 :page-edition: enterprise
 :page-status: beta
+// The following should be global document attributes
+:url-edition: https://www.couchbase.com/products/editions
+:enterprise: {url-edition}[ENTERPRISE EDITION]
+:community: {url-edition}[COMMUNITY EDITION]
+:developer-preview: Developer Preview
 //:page-status: pass:[≥ 5.5]
 
 [abstract]
@@ -131,11 +136,67 @@ If you installed the CLI and the default site generator globally, you can upgrad
  $ npm i -g @antora/cli @antora/site-generator-default
 ====
 
-Now back to monitoring.
+= Edition and Status Labels
 
-= More Monitoring
+You can use spans to add the `edition` and `status` labels to a section, subsection, or paragraph within a document.
 
-Let's get on with it.
+Status labels should only be used to mark that a section is beta or developer preview.
+You could also use it to mark new features, but _only within the version in which the feature was introduced_ -- no-one using version 6.5 needs to know that a feature was introduced in version 4.1.
+
+== Labels for a Section
+
+[.labels]
+[.edition]##{enterprise}##[.status]##{developer-preview}##
+
+To create an edition label, use a span with the role `edition`.
+To create a status label, use a span with the role `status`.
+
+To add edition and status labels at the start of a section or block, place the required spans in a single paragraph on its own.
+To add the "speech bubble tail" above the labels, the spans should be placed in a paragraph with the role `labels`.
+
+Global document attributes are available to insert the content for an edition or status label.
+The global document attribute `{enterprise}` inserts the content for an enterprise edition label.
+The global document attribute `{community}` inserts the content for a community edition label.
+
+If you need to place edition and status labels together, do not insert a space between them.
+In this case, you must use the "inline" span markup, i.e. delimit the spans with double hash marks `##...##`.
+
+== Labels for a Group of Paragraphs within a Section
+
+Here is another section.
+Note that this section does not have any edition or status labels at the start.
+
+****
+[.edition]#{enterprise}#
+
+You can use a sidebar without a title.
+This sidebar shows how you can use the inline label markup in a paragraph on its own to add an edition label or a status label to a collection of blocks which does not form a complete section.
+
+(You should avoid mixing up a section-level labels and block-level labels within one section; it would get too confusing.)
+
+NOTE: Sidebars can contain admonitions.
+
+. Here is a list within the sidebar.
+
+. The edition label at the start of this sidebar clearly applies to the whole content of this sidebar.
+****
+
+Outside the sidebar again.
+The user can clearly see that the edition label within the sidebar does _not_ apply to this paragraph.
+
+== Labels for an Individual Item
+
+Here is another section.
+This section does not have any edition or status labels at the start.
+
+* This is the first item in a list.
+
+* [.edition]#{community}# This is the second item in a list.
+This item is only applicable to community edition.
+
+* This is the third item in the list.
+
+* This is the last item in the list.
 
 [#summary-stats]
 == Bucket Monitoring -- Summary Statistics
@@ -161,7 +222,7 @@ The following statistics are available:
 The `stale=false` view query argument has been enhanced.
 When an application sends a query that has the `stale` parameter set to false, the application receives all recent changes to the documents, including changes that haven't yet been persisted to disk.
 
-[caption="Best practice"]
+[title="Best practice"]
 TIP: For better scalability and throughput, we recommend that you set the value of the `stale` parameter to `ok`.
 With the stream-based views, data returned when `stale` is set to `ok` is closer to the key-value data, even though it might not include all of it.
 

src/css/doc.css

@@ -569,9 +569,7 @@
 }
 
 .doc .sidebarblock > .content {
-  background-color: var(--color-brand-black);
-  color: #fff;
-  font-weight: var(--weight-light);
+  border: 1px solid var(--color-border);
   padding: 3rem;
 }
 

src/css/labels.css

@@ -1,19 +1,30 @@
-.doc .labels ul {
+.doc .labels ul,
+.doc .labels p {
   display: flex;
   list-style: none;
   margin: 0;
   padding: 0.125rem 0 0;
 }
 
-.doc .labels li {
+.doc .labels li,
+.doc .labels span {
   display: block;
-  font-size: 0.75rem;
+  font-size: var(--labels-font-size);
   font-weight: var(--weight-bold);
-  line-height: 1;
+  line-height: var(--labels-line-height);
   position: relative;
 }
 
-.doc .labels li:first-child::before {
+.doc span.edition,
+.doc span.status {
+  max-width: fit-content;
+  font-size: var(--labels-font-size);
+  font-weight: var(--weight-bold);
+  line-height: var(--labels-line-height);
+}
+
+.doc .labels li:first-child::before,
+.doc .labels span:first-child::before {
   content: "";
   display: block;
   position: absolute;
@@ -22,29 +33,42 @@
   top: -1rem;
 }
 
-.doc .labels li > * {
+.doc .labels li > *,
+.doc span.edition,
+.doc span.status {
   color: #fff;
   display: inline-block;
   padding: 0.375em 1em 0.3em;
   text-transform: uppercase;
 }
 
-.doc .labels li a {
+.doc .labels li a,
+.doc span.edition a,
+.doc span.status a {
   text-decoration: none;
 }
 
-.doc .labels li.edition {
+.doc span.edition *,
+.doc span.status * {
+  color: inherit;
+}
+
+.doc .labels li.edition,
+.doc span.edition {
   background-color: var(--color-brand-light-blue);
 }
 
-.doc .labels li.edition::before {
+.doc .labels li.edition::before,
+.doc .labels span.edition::before {
   border-bottom-color: var(--color-brand-light-blue);
 }
 
-.doc .labels li.status {
+.doc .labels li.status,
+.doc span.status {
   background-color: var(--color-brand-orange);
 }
 
-.doc .labels li.status:first-child::before {
+.doc .labels li.status:first-child::before,
+.doc .labels span.status:first-child::before {
   border-bottom-color: var(--color-brand-orange);
 }

src/css/vars.css

@@ -38,6 +38,8 @@
   --height-to-body: calc(var(--height-navbar) + var(--height-spacer));
   --height-min-body: calc(100vh - var(--height-to-body));
   --height-nav: calc(var(--height-min-body) - var(--height-spacer));
+  --labels-font-size: 0.75rem;
+  --labels-line-height: 1;
   /* --width-main-gutter: 1.5rem; */
   --width-main-gutter: 2.5rem;
   --width-container: 90rem;