Removed mention of italics from inline-styles.adoc

Removed mention of italics from basics.adoc

Rewrote attributes-and-roles.adoc

Rewrote pages.adoc

Created a partial to share between those two pages, available-attributes.adoc, to document the attributes in use in Couchbase docs

home/modules/contribute/examples/inline-styles.adoc

@@ -1,7 +1,5 @@
 A bold *word*, a *bold phrase*, and bold c**hara**cter**s**.
 
-An italic _word_, an _italic phrase_, and italic c__hara__cter__s__.
-
 A monospace `word`, a `monospace phrase`, and monospace c``hara``cter``s``.
 
-`*_monospace bold italic phrase_*` and ``**__char__**``acter``**__s__**``
+`*monospace bold phrase*` and ``**char**``acter``**s**``

home/modules/contribute/pages/attributes-and-roles.adoc

@@ -1,22 +1,25 @@
-:page-status: OUT OF DATE
-
 = Attributes and Roles
 
-NOTE: {out-of-date}
+Use attributes and roles to insert content or CSS styles into your pages. 
 
 == Setting and Referencing Document Attributes
 
-AsciiDoc attributes are optional key-value pairs that can be used to hold names, URLs, and reusable content phrases.
-Some attributes are built-in to Asciidoctor; others are defined especially for the Couchbase documentation or by the writer.
+Use an AsciiDoc attribute to hold names, URLs, and reusable content phrases.
+
+An attribute consists of a key-value pair set in a page header or in the playbook file for the documentation site. 
+Some attributes are built-in to Asciidoctor. 
+Others are defined especially for the Couchbase documentation or by the writer.
 
-When defined in the document header, these attributes become available to the whole document and all of its includes.
+Adding an attribute to a document header makes an attribute available to an entire page and all of its includes.
 Each attribute must be entered on a separate line, known as an attribute entry.
 The syntax of an attribute entry as follows:
 
+----
  :name: value
+----
 
 In this case, `name` is the name of the attribute and `value` is the optional value.
-You can see several examples of attribute entries in the listing below.
+The following example shows a document header with multiple included attributes: 
 
 .Examples of document attributes
 [source,asciidoc]
@@ -42,42 +45,74 @@ In this case, the tabs feature is turned on by setting `tabs`.
 <5> Reference an attribute in the body of the document by entering the attribute name inside a set of curly brackets (`+{attribute-name}+`).
 <6> Code blocks are assigned the source language `javascript`.
 
+== Available Document Attributes 
+
+The following document attributes must be included for every AsciiDoc file stored in a *pages* directory: 
+
+include::partial$available-attributes.adoc[tag=required]
+
+You can also use the following optional attributes: 
+
+include::partial$available-attributes.adoc[tag=optional]
+
+Antora also assigns several page attributes on each page to provide information about the component, version, and module where a page is located.
+You can find a list of these attributes in the https://docs.antora.org/antora/latest/page/intrinsic-attributes/[Antora documentation^].
+
+See the https://github.com/couchbase/docs-site/blob/master/antora-playbook.yml[production^] and https://github.com/couchbase/docs-site/blob/master/antora-playbook-staging.yml[staging^] Antora playbooks to review which AsciiDoc attributes are currently set and unset for all of the Couchbase documentation pages.
+
 == Unsetting a Document Attribute
 
 Some built-in attributes are set (turned on) by default and set for all of the Couchbase document in the playbook.
 
-For example, section IDs are automatically generated for all of the Couchbase documentation pages.
-This occurs because the `sectids` attribute is turned on by default.
-To unset (turn off) an attribute on a page, prefix the name with a bang (`!`).
+For example, the `sectids` attribute is turned on by default and automatically generates section IDs for all Couchbase documentation pages.
+To unset (turn off) an attribute on a page, prefix the name with a bang (`!`):
 
 [source,asciidoc]
 ----
 = Page Title
-:!sectids: <1>
+:!sectids:
 ----
-<1> Unset `sectids` with a `!` so that sections IDs are not generated from the section titles in the document.
-
-See the production and staging Antora playbooks to review which AsciiDoc attributes are currently set and unset for all of the Couchbase documentation pages.
 
 == Using Roles
 
 A role applies alternative or additional CSS styles to a document, block, or phrase.
-The styles for each role are defined by the UI.
-A role is applied to a block or phrase by prefixing the role name with a dot and inserting it between a set of square brackets (`[.role-name]`).
+The styles for each role are defined by the code in the https://github.com/couchbase/docs-ui[docs-ui repository^].
+
+=== Inline Roles 
+
+Add a role to a block or phrase by prefixing the role name with a dot and inserting it between a set of square brackets:
+
+[source,asciidoc]
+----
+[.role-name]`I'm a phrase with an assigned role!`
+----
+
+As stated in the https://docs.asciidoctor.org/asciidoc/latest/attributes/role/[AsciiDoc documentation^], inline elements must be surrounded by formatting syntax to be assigned a role. 
+
+You can add multiple roles to a single block or phrase by separating each role name with a period (`.`):
+
+[source,asciidoc]
+----
+[.role1 .role2]*I'm a phrase with an assigned role!*
+
+[.role1 .role2]
+\----
+I'm a block with an assigned role!
+\----
+----
 
-=== Page Role
+=== Page Roles
 
-Assign a role to the page works a little differently.
-When set, the `page-role` attribute applies one or more roles to the entire page.
+Assigning a role to a page applies that role to the entire page, rather than a specific block or phrase.
 `page-role` is an example of a <<Using Page Attributes,page attribute>>.
 It must be defined in the document header.
 
 Unlike with blocks and phrases, page roles are not prefixed with a dot and must be separated by a single space (following the same rules as CSS classes).
 
 The Couchbase documentation currently supports two page roles:
 
-* tiles
-* -toc
+* `tiles`
+* `-toc`
 
 These roles are often combined, as you can see in this example:
 
@@ -95,67 +130,17 @@ The -toc role tells the UI template not to add a table of contents (TOC) to the
 
 == Using Page Attributes
 
-Certain document attributes are reserved specifically for use with Antora.
+Certain document attribute names are reserved specifically for use with Antora.
 These are know as page attributes.
 All page attributes begin with the `page-` prefix.
 The prefix is removed and the remainder is passed on to the UI as metadata.
 For the most part, it's up to the UI to decide how to use this information.
 
-There are several built-in page attribute in Antora and a few others that the Couchbase UI already recognized.
-
-=== Built-in Page Attributes
-
-The built-in page attributes in Antora are as follows:
+Antora has several https://docs.antora.org/antora/latest/page/intrinsic-attributes/[built-in page attributes^], and some other attributes have been added to the Couchbase UI.
 
-page-layout:: Specifies the UI layout to apply to the page.
-If not set, the page layout defaults to `default` (hence loading the `default.hbs` template).
-+
-The home page for the site uses the `home` layout by assigning `:page-layout: home` in the document header.
-
-page-partial:: Indicates that this page may be included in another page.
-Only requires for AsciiDoc files in the pages directory (not the partials directory).
-
-page-aliases:: A comma-separated list of alternate page IDs that should redirect to this page.
-We recommend that, as far as possible, you avoid renaming or moving pages when editing the documentation.
-If you do need to move or rename a page, you will need to list the old page ID in this attribute so that the web server will redirect visitors from the old page to the new location.
-+
-These can be given as just the `.adoc` filename, for a page in the same module:
-+
-[source,asciidoc]
-----
-:page-aliases: search-query.adoc
-----
-+
-Through another module -- `ROOT:search-query.adoc` -- to redirecting to a page in another repo:
-+
-[source,asciidoc]
-----
-:page-aliases: 7.0@server:developer-guide:expiry.adoc
-----
-+
-Note that here the version number must be used to specify which particular page version in the other repo is redirecting to this one.
-
-Antora also assigns several page attributes on each page to provide information about which component, version, and module in which the page is located.
-You can find a list of these attributes in the https://docs.antora.org/antora/2.0/page/page-and-site-attributes/[Antora documentation^].
+WARNING: Do not create your own attributes that conflict with the names of any built-in page attributes or page attributes that are already in use. 
 
 === Custom Page Attributes
 
-Custom page attibutes are used to pass information from the document to the UI.
-It's up to the UI to give these attributes meaning.
-
-The Couchbase UI supports the following custom page attributes:
-
-page-edition:: Used to add a blue badge under the page title that indicates the server edition to which the content applies.
-The badge automatically links to \https://www.couchbase.com/products/editions.
-The value of the attribute is used as the text of the badge.
-
-page-status:: Used to add an orange badge under the page title that indicates the status of the page, such as beta or the minimum software version to which the content applies.
-The value of the attribute is used as the text of the badge.
-
-description:: Sets the value of the meta description in the HTML head.
-Note that the `page-` prefix is not required in this case.
-
-keywords:: Sets the value of the meta keywords in the HTML head.
-Note that the `page-` prefix is not required in this case.
-
-Additional custom page attributes can be added by agreeing on a contract between the page and the UI.
+Use custom page attributes to pass information from the document to the UI.
+Use the https://github.com/couchbase/docs-ui[docs-ui repository^] to control what these attributes actually do with the contents of a page. 

home/modules/contribute/pages/basics.adoc

@@ -6,7 +6,7 @@
 :url-table-width: {url-docs-adoc}/#table-width
 :page-status: OUT OF DATE
 
-== Bold, Italic, and Code Styles
+== Bold and Code Styles
 
 NOTE: {out-of-date}
 
@@ -24,7 +24,6 @@ You can add multiple inline styles to text as long as the syntax is placed in th
 
 * Monospace syntax (`++`++`) is always the outermost formatting set.
 * Bold syntax (`*`) must be outside the italic formatting set.
-* Italic syntax (`_`) is always the innermost formatting set.
 
 To mark up code blocks, include example files, and add callouts, see xref:code-blocks.adoc[Code Blocks and Callouts].
 

home/modules/contribute/pages/pages.adoc

@@ -1,75 +1,124 @@
-:page-status:
-
 = Standard Document Structure
+:basics-link: xref:basics.adoc
+
+All standard AsciiDoc documents exist in the *pages* directory of a module.
+
+== Filenames
+
+AsciiDoc documents should be saved as `.adoc` files, with the following filename restrictions: 
+
+* All lowercase letters.
+* Words separated by hyphens (`-`). 
+* No symbols or special characters.
+
+WARNING: The file's name is used to create its page URL.
+Changing a file's name will break xref:cross-references.adoc[cross references (xrefs)] and incoming links to the page from external websites.
+
+== Internal File Structure
+
+A Couchbase AsciiDoc document file should contain the following components: 
 
-NOTE: {out-of-date}
+A Header:: 
+Contains the document title and document attributes.
+Some attributes are required.
+See <<doc-title,>>. 
 
-A standard AsciiDoc document is stored in the _pages_ directory of a module.
-They have a header, which includes the document title, and a body, which includes the remainder of the document's content.
+A Body::
+Contains the written content, other than the title, that displays when a user visits the page on our documentation site.
+See <<doc-body,>>. 
 
 [#doc-title]
-== Document Title and Header
+=== Document Title and Header
 
-The title of a document is placed on the first line of the file.
-It is specified by one equals sign (`=`), followed by one blank space, and then the text of the title.
-*All AsciiDoc documents stored in a _pages_ directory must have a document title*.
+Put the title of your AsciiDoc document on the first line of the file. 
+Mark the title with one equals sign (`=`), followed by a blank space, and then the title text. 
 
-On the line directly below the title and subsequent contiguous lines, you can add xref:attributes-and-roles.adoc[document attributes].
-Each attribute must be entered on its own line.
-Document attributes are optional.
+NOTE: Every AsciiDoc file stored in a *pages* directory must have a document title.
+
+On the second line and any following lines, you can add xref:attributes-and-roles.adoc[document attributes].
+Each attribute must be entered on its own line, as shown:
 
 ----
 = The Title of My Document
-:page-type: concept
+:page-topic-type: concept
+:description: This is the description of my page! It's short and sweet.
 :url-query-tut: https://query-tutorial.couchbase.com/tutorial/#1
 
+[abstract]
+{description}
+
 This is the body of my document.
 Let's get started with N1QL!
 ----
 
-A single blank line signals the end of the header.
-The document body starts on next line that has text.
+You must include the following document attributes for every AsciiDoc file stored in a *pages* directory: 
 
-== Document Sections
+include::partial$available-attributes.adoc[tag=required]
 
-A document is divided into sections by heading titles.
-Heading 2 section titles, indicated by two equals signs (`==`), are displayed in the xref:nav-menus-and-files.adoc[On This Page sidebar].
+A single blank line signals the end of the header.
+The <<doc-body,document body>> starts on the next line that has text.
 
-----
-== Heading 2 Section Title (H2)
+You can include your own custom document attributes, or make use of some of these other useful attributes, based on your page's content: 
 
-=== Heading 3 Section Title (H3)
+include::partial$available-attributes.adoc[tag=optional]
 
-==== Heading 4 Section Title (H4)
-----
+[#doc-body]
+=== Document Body
+
+Write your document body using appropriate xref:basics.adoc[AsciiDoc syntax]. 
 
-*Don't nest sections out of order*.
-For example, a heading 4 section can't be directly inside a heading 2 section; it must be nested inside a heading 3 section.
+Consider making use of: 
 
-*Don't apply bold formatting to headings*.
+* {basics-link}#bold-and-code-styles[Bold and Code Styles]
+* {basics-link}#ui-macros[Button, Keyboard, and Menu UI Macros]
+* {basics-link}#urls[URLs]
+* {basics-link}#description-lists[Description Lists]
+* {basics-link}#ordered-lists[Ordered Lists]
+* {basics-link}#unordered-lists[Unordered Lists]
+* {basics-link}#images[Images]
+* {basics-link}#admonitions[Admonitions]
+* {basics-link}#tables[Tables]
 
 [#ventilate]
-== Ventilated Prose (aka Sentence Per Line)
+==== Ventilated Prose
 
-Sentences that are part of paragraphs, lists, and tables should be entered on individual lines.
-This best practice makes reviewing pull requests and comparing versions of the same file much easier for maintainers.
+Write in ventilated prose, putting a single sentence on a single line in your AsciiDoc file. 
+Insert paragraph breaks by adding an empty line between sentences: 
 
 ----
-== Establishing Demonstration Indexes
+This is Sentence 1.
+This sentence will display as part of the same paragraph as Sentence 1.
+This is proper ventilated prose. 
 
-The Java SDK code-example provided in xref:java-sdk::full-text-searching-with-sdk.adoc[Searching with the SDK] contains multiple demonstration calls -- each featuring a different query-combination -- and makes use of three different index-definitions, related to the `travel-sample` bucket: for the code example to run successfully, the three indexes must be appropriately pre-established.
-The definitions are provided in xref:fts-demonstration-indexes.adoc[Demonstration Indexes].
+This sentence will start a new paragraph. 
 ----
 
-== File Format and Name
+Ventilated prose makes reviewing pull request and changes easier for reviewers and maintainers. 
+
+==== Headings 
+
+Break up your text into sections using headings.
+Good heading structure makes scanning your documentation easier for readers. 
+
+The number of equals signs (`=`) equals the depth of the heading. 
+
+Heading 2 titles (indicated by 2 equals signs (`==`)) display in the xref:nav-menus-and-files.adoc[On This Page sidebar] on a page.
+You can change the depth of headings displayed on the On This Page sidebar with the <<page-toclevels,:page-toclevels: attribute>>. 
+
+You must nest section headings in order. 
+Do not put an Heading 4 section inside a Heading 2 section, without a Heading 3 section in between: 
+
+----
+== Heading 2 Section Title (H2)
+
+=== Heading 3 Section Title (H3)
+
+==== Heading 4 Section Title (H4)
+----
 
-* Use all lowercase letters.
-* Separate words with hyphens.
-* Save AsciiDoc files with the _.adoc_ extension.
-* Don't use symbols or special characters.
+Vale will flag headings that are not properly ordered inside your document. 
 
-The file's name is used to create its page URL.
-*Changing a file's name will break cross references (xrefs) and incoming links to the page from external websites*.
+You also cannot apply any xref:basics.adoc#bold-italic-and-code-styles[inline formatting] to headings. 
 
 == Learn More