Merge pull request #9773 from chef/self_documenting_resources

Improve resource self documentation

138 files changed, 581 insertions, 251 deletions

diff --git a/chef-config/lib/chef-config/path_helper.rb b/chef-config/lib/chef-config/path_helper.rb
index 2120a83bf6..341f6f583e 100644
--- a/chef-config/lib/chef-config/path_helper.rb
+++ b/chef-config/lib/chef-config/path_helper.rb
@@ -282,7 +282,7 @@ module ChefConfig
       end
     end
 
-    # Determine if the given path is on the exception list for OS X System Integrity Protection.
+    # Determine if the given path is on the exception list for macOS System Integrity Protection.
     def self.writable_sip_path?(path)
       # todo: parse rootless.conf for this?
       sip_exceptions = [
diff --git a/chef-utils/lib/chef-utils/dsl/platform.rb b/chef-utils/lib/chef-utils/dsl/platform.rb
index 1409634e7a..c2ac460ff1 100644
--- a/chef-utils/lib/chef-utils/dsl/platform.rb
+++ b/chef-utils/lib/chef-utils/dsl/platform.rb
@@ -349,7 +349,7 @@ module ChefUtils
         node["platform"] == "suse"
       end
 
-      # Determine if the current node is OpenSUSE.
+      # Determine if the current node is openSUSE.
       #
       # @param [Chef::Node] node the node to check
       # @since 15.5
diff --git a/lib/chef/knife/supermarket_install.rb b/lib/chef/knife/supermarket_install.rb
index 55b32a1774..a3d3aa7a5d 100644
--- a/lib/chef/knife/supermarket_install.rb
+++ b/lib/chef/knife/supermarket_install.rb
@@ -96,7 +96,7 @@ class Chef
         extract_cookbook(upstream_file, downloader.version)
 
         # TODO: it'd be better to store these outside the cookbook repo and
-        # keep them around, e.g., in ~/Library/Caches on OS X.
+        # keep them around, e.g., in ~/Library/Caches on macOS.
         ui.info("Removing downloaded tarball")
         File.unlink(upstream_file)
 
diff --git a/lib/chef/provider/user/dscl.rb b/lib/chef/provider/user/dscl.rb
index 34c5e82d45..39faa3d45c 100644
--- a/lib/chef/provider/user/dscl.rb
+++ b/lib/chef/provider/user/dscl.rb
@@ -28,7 +28,7 @@ class Chef
     class User
       #
       # The most tricky bit of this provider is the way it deals with user passwords.
-      # Mac OS X has different password shadow calculations based on the version.
+      # macOS has different password shadow calculations based on the version.
       # < 10.7  => password shadow calculation format SALTED-SHA1
       #         => stored in: /var/db/shadow/hash/#{guid}
       #         => shadow binary length 68 bytes
diff --git a/lib/chef/resource/alternatives.rb b/lib/chef/resource/alternatives.rb
index 9e1fb8322f..58de3d5102 100644
--- a/lib/chef/resource/alternatives.rb
+++ b/lib/chef/resource/alternatives.rb
@@ -29,7 +29,7 @@ class Chef
       description "The alternatives resource allows for configuration of command alternatives in Linux using the alternatives or update-alternatives packages."
       introduced "16.0"
       examples <<~DOC
-      Install an alternative
+      **Install an alternative**:
 
       ```ruby
       alternatives 'python install 2' do
@@ -40,7 +40,7 @@ class Chef
       end
       ```
 
-      Set an alternative
+      **Set an alternative**:
 
       ```ruby
       alternatives 'python set version 3' do
@@ -50,7 +50,7 @@ class Chef
       end
       ```
 
-      Set the automatic alternative state
+      **Set the automatic alternative state**:
 
       ```ruby
       alternatives 'python auto' do
@@ -59,7 +59,7 @@ class Chef
       end
       ```
 
-      Refresh an alternative
+      **Refresh an alternative**:
 
       ```ruby
       alternatives 'python refresh' do
@@ -68,7 +68,7 @@ class Chef
       end
       ```
 
-      Remove an alternative
+      **Remove an alternative**:
 
       ```ruby
       alternatives 'python remove' do
diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 9889843e26..9ecbbe9153 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -26,7 +26,7 @@ class Chef
       provides :apt_package, target_mode: true
       provides :package, platform_family: "debian", target_mode: true
 
-      description "Use the apt_package resource to manage packages on Debian and Ubuntu platforms."
+      description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms."
 
       property :default_release, String,
         description: "The default release. For example: `stable`.",
diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 1c910c99a5..0fcce64d2d 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides(:apt_preference) { true }
 
-      description "The apt_preference resource allows for the creation of APT preference files. Preference files are used to control which package versions and sources are prioritized during installation."
+      description "Use the **apt_preference** resource to create APT [preference files](https://wiki.debian.org/AptPreferences). Preference files are used to control which package versions and sources are prioritized during installation."
       introduced "13.3"
 
       property :package_name, String,
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 1a6ea10522..282c7a70eb 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -28,11 +28,12 @@ class Chef
 
       provides(:apt_repository) { true }
 
-      description "Use the apt_repository resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
+      description "Use the **apt_repository** resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
       introduced "12.9"
 
       examples <<~DOC
-        Add repository with basic settings
+        **Add repository with basic settings**:
+
          ```ruby
         apt_repository 'nginx' do
           uri        'http://nginx.org/packages/ubuntu/'
@@ -40,29 +41,32 @@ class Chef
         end
         ```
 
-        Enable Ubuntu multiverse repositories
+        **Enable Ubuntu multiverse repositories**:
+
         ```ruby
         apt_repository 'security-ubuntu-multiverse' do
           uri          'http://security.ubuntu.com/ubuntu'
-          distribution 'trusty-security'
+          distribution 'xenial-security'
           components   ['multiverse']
           deb_src      true
         end
         ```
 
-        Add the Nginx PPA, autodetect the key and repository url
+        **Add the Nginx PPA, autodetect the key and repository url**:
+
         ```ruby
         apt_repository 'nginx-php' do
           uri          'ppa:nginx/stable'
         end
         ```
 
-        Add the JuJu PPA, grab the key from the keyserver, and add source repo
+        **Add the JuJu PPA, grab the key from the keyserver, and add source repo**:
+
         ```ruby
         apt_repository 'juju' do
           uri 'http://ppa.launchpad.net/juju/stable/ubuntu'
           components ['main']
-          distribution 'trusty'
+          distribution 'xenial'
           key 'C8068B11'
           keyserver 'keyserver.ubuntu.com'
           action :add
@@ -70,7 +74,8 @@ class Chef
         end
         ```
 
-        Add repository that requires multiple keys to authenticate packages
+        **Add repository that requires multiple keys to authenticate packages**:
+
         ```ruby
         apt_repository 'rundeck' do
           uri 'https://dl.bintray.com/rundeck/rundeck-deb'
@@ -81,18 +86,20 @@ class Chef
         end
         ```
 
-        Add the Cloudera Repo of CDH4 packages for Ubuntu 12.04 on AMD64
+        **Add the Cloudera Repo of CDH4 packages for Ubuntu 16.04 on AMD64**:
+
         ```ruby
         apt_repository 'cloudera' do
-          uri          'http://archive.cloudera.com/cdh4/ubuntu/precise/amd64/cdh'
+          uri          'http://archive.cloudera.com/cdh4/ubuntu/xenial/amd64/cdh'
           arch         'amd64'
-          distribution 'precise-cdh4'
+          distribution 'xenial-cdh4'
           components   ['contrib']
           key          'http://archive.cloudera.com/debian/archive.key'
         end
         ```
 
-        Remove a repository from the list
+        **Remove a repository from the list**:
+
         ```ruby
         apt_repository 'zenoss' do
           action :remove
diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index a2ca6aa5e0..e5f75143bb 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -25,10 +25,11 @@ class Chef
 
       provides(:apt_update) { true }
 
-      description "Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms."
+      description "Use the **apt_update** resource to manage APT repository updates on Debian and Ubuntu platforms."
       introduced "12.7"
       examples <<~DOC
-        Update the Apt repository at a specified interval
+        **Update the Apt repository at a specified interval**:
+
         ```ruby
         apt_update 'all platforms' do
         frequency 86400
@@ -36,7 +37,8 @@ class Chef
         end
         ```
 
-        Update the Apt repository at the start of a Chef Infra Client run
+        **Update the Apt repository at the start of a Chef Infra Client run**:
+
         ```ruby
         apt_update 'update'
         ```
diff --git a/lib/chef/resource/archive_file.rb b/lib/chef/resource/archive_file.rb
index b288cb4885..58e106d9bc 100644
--- a/lib/chef/resource/archive_file.rb
+++ b/lib/chef/resource/archive_file.rb
@@ -29,9 +29,10 @@ class Chef
       provides :libarchive_file # legacy cookbook name
 
       introduced "15.0"
-      description "Use the archive_file resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
+      description "Use the **archive_file** resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
       examples <<~DOC
-        Extract a zip file to a specified directory
+        **Extract a zip file to a specified directory**:
+
         ```ruby
         archive_file 'Precompiled.zip' do
           path '/tmp/Precompiled.zip'
diff --git a/lib/chef/resource/bash.rb b/lib/chef/resource/bash.rb
index d0ed76f305..98d110eb1b 100644
--- a/lib/chef/resource/bash.rb
+++ b/lib/chef/resource/bash.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :bash
 
-      description "Use the bash resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+      description "Use the **bash** resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/batch.rb b/lib/chef/resource/batch.rb
index 814a9314c6..a524737abe 100644
--- a/lib/chef/resource/batch.rb
+++ b/lib/chef/resource/batch.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :batch
 
-      description "Use the batch resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+      description "Use the **batch** resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
         super(name, run_context, nil, "cmd.exe")
diff --git a/lib/chef/resource/bff_package.rb b/lib/chef/resource/bff_package.rb
index 625d48626e..5c18373b32 100644
--- a/lib/chef/resource/bff_package.rb
+++ b/lib/chef/resource/bff_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :bff_package
 
-      description "Use the bff_package resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **bff_package** resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
       introduced "12.0"
 
       property :package_name, String,
diff --git a/lib/chef/resource/breakpoint.rb b/lib/chef/resource/breakpoint.rb
index 557b10bcd1..d1e6bbf179 100644
--- a/lib/chef/resource/breakpoint.rb
+++ b/lib/chef/resource/breakpoint.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :breakpoint, target_mode: true
 
-      description "Use the breakpoint resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
+      description "Use the **breakpoint** resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
       introduced "12.0"
 
       default_action :break
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 2151bd715b..c83517fdfe 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -24,22 +24,25 @@ class Chef
 
       provides(:build_essential) { true }
 
-      description "Use the build_essential resource to install the packages required for compiling C software from source."
+      description "Use the **build_essential** resource to install the packages required for compiling C software from source."
       introduced "14.0"
       examples <<~DOC
-        Install compilation packages
+        **Install compilation packages**:
+
         ```ruby
         build_essential
         ```
 
-        Install compilation packages during the compilation phase
+        **Install compilation packages during the compilation phase**:
+
         ```ruby
         build_essential 'Install compilation tools' do
           compile_time true
         end
         ```
 
-        Upgrade compilation packages on macOS systems
+        **Upgrade compilation packages on macOS systems**:
+
         ```ruby
         build_essential 'Install compilation tools' do
           action :upgrade
@@ -52,6 +55,7 @@ class Chef
 
       property :raise_if_unsupported, [TrueClass, FalseClass],
         description: "Raise a hard error on platforms where this resource is unsupported.",
+        introduced: "15.5",
         default: false, desired_state: false # FIXME: make this default to true
 
       action :install do
diff --git a/lib/chef/resource/cab_package.rb b/lib/chef/resource/cab_package.rb
index f0a6063477..374eac56a4 100644
--- a/lib/chef/resource/cab_package.rb
+++ b/lib/chef/resource/cab_package.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides :cab_package
 
-      description "Use the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages."
+      description "Use the **cab_package** resource to install or remove Microsoft Windows cabinet (.cab) packages."
       introduced "12.15"
 
       allowed_actions :install, :remove
diff --git a/lib/chef/resource/chef_client_cron.rb b/lib/chef/resource/chef_client_cron.rb
index 5ef68e5b55..974bd5e909 100644
--- a/lib/chef/resource/chef_client_cron.rb
+++ b/lib/chef/resource/chef_client_cron.rb
@@ -26,15 +26,17 @@ class Chef
 
       provides :chef_client_cron
 
-      description "Use the chef_client_cron resource to setup the #{Chef::Dist::PRODUCT} to run as a cron job. This resource will also create the specified log directory if it doesn't already exist."
+      description "Use the **chef_client_cron** resource to setup the #{Chef::Dist::PRODUCT} to run as a cron job. This resource will also create the specified log directory if it doesn't already exist."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
       chef_client_cron "Run #{Chef::Dist::PRODUCT} as a cron job"
       ```
 
-      Run #{Chef::Dist::PRODUCT} twice a day
+      **Run #{Chef::Dist::PRODUCT} twice a day**:
+
       ```ruby
       chef_client_cron "Run #{Chef::Dist::PRODUCT} every 12 hours" do
         minute 0
@@ -42,7 +44,8 @@ class Chef
       end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
       chef_client_cron "Run an override recipe" do
         daemon_options ["--override-runlist mycorp_base::default"]
diff --git a/lib/chef/resource/chef_client_scheduled_task.rb b/lib/chef/resource/chef_client_scheduled_task.rb
index 816b704213..f5a7e5a4e7 100644
--- a/lib/chef/resource/chef_client_scheduled_task.rb
+++ b/lib/chef/resource/chef_client_scheduled_task.rb
@@ -24,22 +24,25 @@ class Chef
 
       provides :chef_client_scheduled_task
 
-      description "Use the chef_client_scheduled_task resource to setup the #{Chef::Dist::PRODUCT} to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn't already exist."
+      description "Use the **chef_client_scheduled_task** resource to setup the #{Chef::Dist::PRODUCT} to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn't already exist."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
         chef_client_scheduled_task "Run #{Chef::Dist::PRODUCT} as a scheduled task"
       ```
 
-      Run #{Chef::Dist::PRODUCT} on system start
+      **Run #{Chef::Dist::PRODUCT} on system start**:
+
       ```ruby
         chef_client_scheduled_task '#{Chef::Dist::PRODUCT} on start' do
           frequency 'onstart'
         end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
         chef_client_scheduled_task "Run an override recipe" do
           daemon_options ["--override-runlist mycorp_base::default"]
diff --git a/lib/chef/resource/chef_client_systemd_timer.rb b/lib/chef/resource/chef_client_systemd_timer.rb
index b174faef14..4ca32a08cc 100644
--- a/lib/chef/resource/chef_client_systemd_timer.rb
+++ b/lib/chef/resource/chef_client_systemd_timer.rb
@@ -24,22 +24,25 @@ class Chef
 
       provides :chef_client_systemd_timer
 
-      description "Use the chef_client_systemd_timer resource to setup the #{Chef::Dist::PRODUCT} to run as a systemd timer."
+      description "Use the **chef_client_systemd_timer** resource to setup the #{Chef::Dist::PRODUCT} to run as a systemd timer."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
       chef_client_systemd_timer "Run #{Chef::Dist::PRODUCT} as a systemd timer"
       ```
 
-      Run #{Chef::Dist::PRODUCT} every 1 hour
+      **Run #{Chef::Dist::PRODUCT} every 1 hour**:
+
       ```ruby
       chef_client_systemd_timer "Run #{Chef::Dist::PRODUCT} every 1 hour" do
         interval "1hr"
       end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
       chef_client_systemd_timer "Run an override recipe" do
         daemon_options ["--override-runlist mycorp_base::default"]
diff --git a/lib/chef/resource/chef_handler.rb b/lib/chef/resource/chef_handler.rb
index e1f4829666..0138baeaec 100644
--- a/lib/chef/resource/chef_handler.rb
+++ b/lib/chef/resource/chef_handler.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides(:chef_handler) { true }
 
-      description "Use the chef_handler resource to install or uninstall reporting/exception handlers."
+      description "Use the **chef_handler** resource to install or uninstall reporting/exception handlers."
       introduced "14.0"
 
       property :class_name, String,
diff --git a/lib/chef/resource/chef_sleep.rb b/lib/chef/resource/chef_sleep.rb
index 4d589ff6a4..828ce07bc9 100644
--- a/lib/chef/resource/chef_sleep.rb
+++ b/lib/chef/resource/chef_sleep.rb
@@ -24,22 +24,25 @@ class Chef
 
       unified_mode true
 
-      description "Use the chef_sleep resource to set the number of seconds to sleep during a #{Chef::Dist::PRODUCT} run. Only use this resource when a command or service exits successfully but is not ready for the next step of the recipe."
+      description "Use the **chef_sleep** resource to pause (sleep) for a number of seconds during a #{Chef::Dist::PRODUCT} run. Only use this resource when a command or service exits successfully but is not ready for the next step in a recipe."
       introduced "15.5"
       examples <<~DOC
-        Sleep for 10 seconds
+        **Sleep for 10 seconds**:
+
         ```ruby
         chef_sleep '10'
         ```
 
-        Sleep for 10 seconds with a descriptive resource name for logging
+        **Sleep for 10 seconds with a descriptive resource name for logging**:
+
         ```ruby
         chef_sleep 'wait for the service to start' do
           seconds 10
         end
         ````
 
-        Use a notification from another resource to sleep only when necessary
+        **Use a notification from another resource to sleep only when necessary**:
+
         ```ruby
         service 'Service that is slow to start and reports as started' do
           service_name 'my_database'
diff --git a/lib/chef/resource/chef_vault_secret.rb b/lib/chef/resource/chef_vault_secret.rb
index e63907fe07..551962d86e 100644
--- a/lib/chef/resource/chef_vault_secret.rb
+++ b/lib/chef/resource/chef_vault_secret.rb
@@ -26,9 +26,9 @@ class Chef
       provides :chef_vault_secret
 
       introduced "16.0"
-      description "Use the chef_vault_secret resource to store secrets in Chef Vault items. Where possible and relevant, this resource attempts to map behavior and functionality to the knife vault sub-commands."
+      description "Use the **chef_vault_secret** resource to store secrets in Chef Vault items. Where possible and relevant, this resource attempts to map behavior and functionality to the knife vault sub-commands."
       examples <<~DOC
-        To create a 'foo' item in an existing 'bar' data bag:
+        **To create a 'foo' item in an existing 'bar' data bag**:
 
         ```ruby
         chef_vault_secret 'foo' do
@@ -39,7 +39,7 @@ class Chef
         end
         ```
 
-        To allow multiple admins access to an item:
+        **To allow multiple admins access to an item**:
 
         ```ruby
         chef_vault_secret 'root-password' do
diff --git a/lib/chef/resource/chocolatey_config.rb b/lib/chef/resource/chocolatey_config.rb
index 455f071458..c4f100c28d 100644
--- a/lib/chef/resource/chocolatey_config.rb
+++ b/lib/chef/resource/chocolatey_config.rb
@@ -21,10 +21,11 @@ class Chef
 
       provides :chocolatey_config
 
-      description "Use the chocolatey_config resource to add or remove Chocolatey configuration keys."
+      description "Use the **chocolatey_config** resource to add or remove Chocolatey configuration keys."
       introduced "14.3"
       examples <<~DOC
-        Set the Chocolatey cacheLocation config
+        **Set the Chocolatey cacheLocation config**:
+
         ```ruby
         chocolatey_config 'Set cacheLocation config' do
           config_key 'cacheLocation'
@@ -32,7 +33,8 @@ class Chef
         end
         ```
 
-        Unset a Chocolatey config
+        **Unset a Chocolatey config**:
+
         ```ruby
         chocolatey_config 'BogusConfig' do
           action :unset
diff --git a/lib/chef/resource/chocolatey_feature.rb b/lib/chef/resource/chocolatey_feature.rb
index cd987ea3c1..3b24ebbc9c 100644
--- a/lib/chef/resource/chocolatey_feature.rb
+++ b/lib/chef/resource/chocolatey_feature.rb
@@ -20,17 +20,19 @@ class Chef
       unified_mode true
       provides :chocolatey_feature
 
-      description "Use the chocolatey_feature resource to enable and disable Chocolatey features."
+      description "Use the **chocolatey_feature** resource to enable and disable Chocolatey features."
       introduced "15.1"
       examples <<~DOC
-        Enable the checksumFiles Chocolatey feature
+        **Enable the checksumFiles Chocolatey feature**
+
         ```ruby
         chocolatey_feature 'checksumFiles' do
           action :enable
         end
         ```
 
-        Disable the checksumFiles Chocolatey feature
+        **Disable the checksumFiles Chocolatey feature**
+
         ```ruby
         chocolatey_feature 'checksumFiles' do
           action :disable
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index 7beefb5ef5..9d2d7bfffe 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -25,17 +25,19 @@ class Chef
 
       provides :chocolatey_package
 
-      description "Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform."
+      description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform."
       introduced "12.7"
       examples <<~DOC
-        Install a Chocolatey package
+        **Install a Chocolatey package**:
+
         ```ruby
         chocolatey_package 'name of package' do
           action :install
         end
         ```
 
-        Install a package with options with Chocolatey's `--checksum` option
+        **Install a package with options with Chocolatey's `--checksum` option**:
+
         ```ruby
         chocolatey_package 'name of package' do
           options '--checksum 1234567890'
diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb
index 1debd45953..cee4289682 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -20,10 +20,11 @@ class Chef
       unified_mode true
       provides :chocolatey_source
 
-      description "Use the chocolatey_source resource to add, remove, enable, or disable Chocolatey sources."
+      description "Use the **chocolatey_source** resource to add, remove, enable, or disable Chocolatey sources."
       introduced "14.3"
       examples <<~DOC
-        Add a Chocolatey source
+        **Add a Chocolatey source**
+
         ```ruby
         chocolatey_source 'MySource' do
           source 'http://example.com/something'
@@ -31,7 +32,8 @@ class Chef
         end
         ```
 
-        Remove a Chocolatey source
+        **Remove a Chocolatey source**
+
         ```ruby
         chocolatey_source 'MySource' do
           action :remove
diff --git a/lib/chef/resource/cookbook_file.rb b/lib/chef/resource/cookbook_file.rb
index 01fb395c10..7a2cb6f236 100644
--- a/lib/chef/resource/cookbook_file.rb
+++ b/lib/chef/resource/cookbook_file.rb
@@ -31,7 +31,7 @@ class Chef
 
       provides :cookbook_file
 
-      description "Use the cookbook_file resource to transfer files from a sub-directory of COOKBOOK_NAME/files/ to a specified path located on a host that is running the #{Chef::Dist::PRODUCT}. The file is selected according to file specificity, which allows different source files to be used based on the hostname, host platform (operating system, distro, or as appropriate), or platform version. Files that are located in the COOKBOOK_NAME/files/default sub-directory may be used on any platform.\n\nDuring a #{Chef::Dist::PRODUCT} run, the checksum for each local file is calculated and then compared against the checksum for the same file as it currently exists in the cookbook on the #{Chef::Dist::SERVER_PRODUCT}. A file is not transferred when the checksums match. Only files that require an update are transferred from the #{Chef::Dist::SERVER_PRODUCT} to a node."
+      description "Use the **cookbook_file** resource to transfer files from a sub-directory of COOKBOOK_NAME/files/ to a specified path located on a host that is running the #{Chef::Dist::PRODUCT}. The file is selected according to file specificity, which allows different source files to be used based on the hostname, host platform (operating system, distro, or as appropriate), or platform version. Files that are located in the COOKBOOK_NAME/files/default sub-directory may be used on any platform.\n\nDuring a #{Chef::Dist::PRODUCT} run, the checksum for each local file is calculated and then compared against the checksum for the same file as it currently exists in the cookbook on the #{Chef::Dist::SERVER_PRODUCT}. A file is not transferred when the checksums match. Only files that require an update are transferred from the #{Chef::Dist::SERVER_PRODUCT} to a node."
 
       property :source, [ String, Array ],
         description: "The name of the file in COOKBOOK_NAME/files/default or the path to a file located in COOKBOOK_NAME/files. The path must include the file name and its extension. This can be used to distribute specific files depending upon the platform used.",
diff --git a/lib/chef/resource/cron.rb b/lib/chef/resource/cron.rb
index a274bbeefe..6caeaf7d97 100644
--- a/lib/chef/resource/cron.rb
+++ b/lib/chef/resource/cron.rb
@@ -27,7 +27,7 @@ class Chef
       unified_mode true
       provides :cron
 
-      description "Use the cron resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron."
+      description "Use the **cron** resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron."
 
       state_attrs :minute, :hour, :day, :month, :weekday, :user
 
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index 6591993c49..f995c9b454 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -28,21 +28,24 @@ class Chef
       provides(:cron_manage) # legacy name @todo in Chef 15 we should { true } this so it wins over the cookbook
 
       introduced "14.4"
-      description "Use the cron_access resource to manage the /etc/cron.allow and /etc/cron.deny files."
+      description "Use the **cron_access** resource to manage the /etc/cron.allow and /etc/cron.deny files."
       examples <<~DOC
-        Add the mike user to cron.allow
+        **Add the mike user to cron.allow**
+
         ```ruby
         cron_access 'mike'
         ```
 
-        Add the mike user to cron.deny
+        **Add the mike user to cron.deny**
+
         ```ruby
         cron_access 'mike' do
           action :deny
         end
         ```
 
-        Specify the username with the user property
+        **Specify the username with the user property**
+
         ```ruby
         cron_access 'Deny the jenkins user access to cron for security purposes' do
           user 'jenkins'
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index 94e855e51f..2863a88380 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -27,9 +27,10 @@ class Chef
       provides :cron_d
 
       introduced "14.4"
-      description "Use the cron_d resource to manage cron job files in the /etc/cron.d directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+      description "Use the **cron_d** resource to manage cron job files in the /etc/cron.d directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
       examples <<~DOC
-        To run a program on the fifth hour of the day
+        **Run a program on the fifth hour of the day**
+
         ```ruby
         cron_d 'noop' do
           hour '5'
@@ -38,7 +39,8 @@ class Chef
         end
         ```
 
-        To run an entry if a folder exists
+        **Run an entry if a folder exists**
+
         ```ruby
         cron_d 'ganglia_tomcat_thread_max' do
           command "/usr/bin/gmetric
@@ -50,7 +52,8 @@ class Chef
         end
         ```
 
-        To run an entry every Saturday, 8:00 AM
+        **Run an entry every Saturday, 8:00 AM**
+
         ```ruby
         cron_d 'name_of_cron_entry' do
           minute '0'
@@ -61,7 +64,8 @@ class Chef
         end
         ```
 
-        To run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November
+        **Run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November**
+
         ```ruby
         cron_d 'name_of_cron_entry' do
           minute '0'
diff --git a/lib/chef/resource/csh.rb b/lib/chef/resource/csh.rb
index c584090746..82c695edc7 100644
--- a/lib/chef/resource/csh.rb
+++ b/lib/chef/resource/csh.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :csh
 
-      description "Use the csh resource to execute scripts using the csh interpreter."\
+      description "Use the **csh** resource to execute scripts using the csh interpreter."\
                   " This resource may also use any of the actions and properties that are"\
                   " available to the execute resource. Commands that are executed with this"\
                   " resource are (by their nature) not idempotent, as they are typically"\
diff --git a/lib/chef/resource/directory.rb b/lib/chef/resource/directory.rb
index 06c43c95df..d51fb144f7 100644
--- a/lib/chef/resource/directory.rb
+++ b/lib/chef/resource/directory.rb
@@ -28,7 +28,7 @@ class Chef
 
       provides :directory
 
-      description "Use the directory resource to manage a directory, which is a hierarchy"\
+      description "Use the **directory** resource to manage a directory, which is a hierarchy"\
                   " of folders that comprises all of the information stored on a computer."\
                   " The root directory is the top-level, under which the rest of the directory"\
                   " is organized. The directory resource uses the name property to specify the"\
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 14b16a9284..37382dd621 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -24,10 +24,11 @@ class Chef
 
       provides(:dmg_package) { true }
 
-      description "Use the dmg_package resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using OS X's hdidutil, copy the application (.app directory) to the specified destination (/Applications), and detach the image using hdiutil. The dmg file will be stored in the Chef::Config[:file_cache_path]."
+      description "Use the **dmg_package** resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using macOS' `hdidutil`, copy the application (.app directory) to the specified destination (`/Applications`), and detach the image using `hdiutil`. The dmg file will be stored in the `Chef::Config[:file_cache_path]``."
       introduced "14.0"
       examples <<~DOC
-        Install Google Chrome via the DMG package
+        **Install Google Chrome via the DMG package**:
+
         ```ruby
         dmg_package 'Google Chrome' do
           dmg_name 'googlechrome'
@@ -37,7 +38,8 @@ class Chef
         end
         ```
 
-        Install Virtualbox from the .mpkg
+        **Install Virtualbox from the .mpkg**:
+
         ```ruby
         dmg_package 'Virtualbox' do
           source 'http://dlc.sun.com.edgesuite.net/virtualbox/4.0.8/VirtualBox-4.0.8-71778-OSX.dmg'
@@ -45,7 +47,8 @@ class Chef
         end
         ```
 
-        Install pgAdmin and automatically accept the EULA
+        **Install pgAdmin and automatically accept the EULA**:
+
         ```ruby
         dmg_package 'pgAdmin3' do
           source   'http://wwwmaster.postgresql.org/redir/198/h/pgadmin3/release/v1.12.3/osx/pgadmin3-1.12.3.dmg'
diff --git a/lib/chef/resource/dnf_package.rb b/lib/chef/resource/dnf_package.rb
index b89c1302ae..b2401c797d 100644
--- a/lib/chef/resource/dnf_package.rb
+++ b/lib/chef/resource/dnf_package.rb
@@ -40,7 +40,7 @@ class Chef
         which("dnf")
       end
 
-      description "Use the dnf_package resource to install, upgrade, and remove packages with DNF for Fedora and RHEL 8+. The dnf_package resource is able to resolve provides data for packages much like DNF can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides and library names."
+      description "Use the **dnf_package** resource to install, upgrade, and remove packages with DNF for Fedora and RHEL 8+. The dnf_package resource is able to resolve provides data for packages much like DNF can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides and library names."
       introduced "12.18"
 
       allowed_actions :install, :upgrade, :remove, :purge, :reconfig, :lock, :unlock, :flush_cache
diff --git a/lib/chef/resource/dpkg_package.rb b/lib/chef/resource/dpkg_package.rb
index 0a53b517fa..ffc15b49c5 100644
--- a/lib/chef/resource/dpkg_package.rb
+++ b/lib/chef/resource/dpkg_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :dpkg_package
 
-      description "Use the dpkg_package resource to manage packages for the dpkg platform. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **dpkg_package** resource to manage packages for the dpkg platform. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
 
       property :source, [ String, Array, nil ],
         description: "The path to a package in the local file system."
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index 9195f7a4d6..192210799c 100644
--- a/lib/chef/resource/execute.rb
+++ b/lib/chef/resource/execute.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides :execute, target_mode: true
 
-      description "Use the execute resource to execute a single command. Commands that"\
+      description "Use the **execute** resource to execute a single command. Commands that"\
                   " are executed with this resource are (by their nature) not idempotent,"\
                   " as they are typically unique to the environment in which they are run."\
                   " Use not_if and only_if to guard this resource for idempotence."
@@ -100,7 +100,7 @@ class Chef
         default: lazy { password ? true : false }, default_description: "True if the password property is set. False otherwise."
 
       property :elevated, [ TrueClass, FalseClass ], default: false,
-        description: "Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) interactively blocking the process.\nThis will cause the process to be run under a batch login instead of an interactive login. The user running #{Chef::Dist::CLIENT} needs the “Replace a process level token” and “Adjust Memory Quotas for a process” permissions. The user that is running the command needs the “Log on as a batch job” permission.\nBecause this requires a login, the user and password properties are required.",
+        description: "Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) interactively blocking the process.\nThis will cause the process to be run under a batch login instead of an interactive login. The user running #{Chef::Dist::CLIENT} needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission.\nBecause this requires a login, the user and password properties are required.",
         introduced: "13.3"
 
       alias :env :environment
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index 930e044846..cd848585cf 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -32,7 +32,7 @@ class Chef
 
       provides :file
 
-      description "Use the file resource to manage files directly on a node."
+      description "Use the **file** resource to manage files directly on a node."
 
       if ChefUtils.windows?
         # Use Windows rights instead of standard *nix permissions
diff --git a/lib/chef/resource/freebsd_package.rb b/lib/chef/resource/freebsd_package.rb
index f601f1143b..4e0c161094 100644
--- a/lib/chef/resource/freebsd_package.rb
+++ b/lib/chef/resource/freebsd_package.rb
@@ -29,7 +29,7 @@ class Chef
       provides :freebsd_package
       provides :package, platform: "freebsd"
 
-      description "Use the freebsd_package resource to manage packages for the FreeBSD platform."
+      description "Use the **freebsd_package** resource to manage packages for the FreeBSD platform."
 
       # make sure we assign the appropriate underlying providers based on what
       # package managers exist on this FreeBSD system or the source of the package
diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb
index a5184f41d6..96da7fd513 100644
--- a/lib/chef/resource/gem_package.rb
+++ b/lib/chef/resource/gem_package.rb
@@ -25,7 +25,7 @@ class Chef
       unified_mode true
       provides :gem_package
 
-      description "Use the gem_package resource to manage gem packages that are only included in recipes. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **gem_package** resource to manage gem packages that are only included in recipes. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/group.rb b/lib/chef/resource/group.rb
index b47bd36520..3a129592d0 100644
--- a/lib/chef/resource/group.rb
+++ b/lib/chef/resource/group.rb
@@ -23,7 +23,7 @@ class Chef
       unified_mode true
       state_attrs :members
 
-      description "Use the group resource to manage a local group."
+      description "Use the **group** resource to manage a local group."
 
       provides :group
 
diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb
index 303368acda..3b0974348c 100644
--- a/lib/chef/resource/homebrew_cask.rb
+++ b/lib/chef/resource/homebrew_cask.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides(:homebrew_cask) { true }
 
-      description "Use the homebrew_cask resource to install binaries distributed via the Homebrew package manager."
+      description "Use the **homebrew_cask** resource to install binaries distributed via the Homebrew package manager."
       introduced "14.0"
 
       include Chef::Mixin::HomebrewUser
diff --git a/lib/chef/resource/homebrew_package.rb b/lib/chef/resource/homebrew_package.rb
index 5bcba3ed56..71a9ffde38 100644
--- a/lib/chef/resource/homebrew_package.rb
+++ b/lib/chef/resource/homebrew_package.rb
@@ -29,7 +29,7 @@ class Chef
       provides :homebrew_package
       provides :package, os: "darwin"
 
-      description "Use the homebrew_package resource to manage packages for the macOS platform."
+      description "Use the **homebrew_package** resource to manage packages for the macOS platform."
       introduced "12.0"
 
       property :homebrew_user, [ String, Integer ],
diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb
index b5a7a201ef..937a9ab420 100644
--- a/lib/chef/resource/homebrew_tap.rb
+++ b/lib/chef/resource/homebrew_tap.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides(:homebrew_tap) { true }
 
-      description "Use the homebrew_tap resource to add additional formula repositories to the Homebrew package manager."
+      description "Use the **homebrew_tap** resource to add additional formula repositories to the Homebrew package manager."
       introduced "14.0"
 
       include Chef::Mixin::HomebrewUser
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index d6e08175ea..9d4dd03aa7 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -23,16 +23,16 @@ class Chef
 
       provides :hostname
 
-      description "Use the hostname resource to set the system's hostname, configure hostname and hosts config file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks."
+      description "Use the **hostname** resource to set the system's hostname, configure hostname and hosts config file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks."
       introduced "14.0"
       examples <<~DOC
-        Set the hostname using the IP address, as detected by Ohai
+        **Set the hostname using the IP address, as detected by Ohai**:
 
         ```ruby
         hostname 'example'
         ```
 
-        Manually specify the hostname and IP address
+        **Manually specify the hostname and IP address**:
 
         ```ruby
         hostname 'statically_configured_host' do
@@ -168,7 +168,7 @@ class Chef
               # older non-systemd RHEL/Fedora derived
               append_replacing_matching_lines("/etc/sysconfig/network", /^HOSTNAME\s*=/, "HOSTNAME=#{new_resource.hostname}")
             when ::File.exist?("/etc/HOSTNAME")
-              # SuSE/OpenSUSE uses /etc/HOSTNAME
+              # SuSE/openSUSE uses /etc/HOSTNAME
               declare_resource(:file, "/etc/HOSTNAME") do
                 content "#{new_resource.hostname}\n"
                 owner "root"
diff --git a/lib/chef/resource/http_request.rb b/lib/chef/resource/http_request.rb
index 97b0ff8ac4..de714ab4ab 100644
--- a/lib/chef/resource/http_request.rb
+++ b/lib/chef/resource/http_request.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :http_request
 
-      description "Use the http_request resource to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This resource is often useful when custom callbacks are necessary."
+      description "Use the **http_request** resource to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This resource is often useful when custom callbacks are necessary."
 
       default_action :get
       allowed_actions :get, :patch, :put, :post, :delete, :head, :options
diff --git a/lib/chef/resource/ifconfig.rb b/lib/chef/resource/ifconfig.rb
index 8d74b27fc6..ed62ab5952 100644
--- a/lib/chef/resource/ifconfig.rb
+++ b/lib/chef/resource/ifconfig.rb
@@ -30,7 +30,7 @@ class Chef
 
       provides :ifconfig
 
-      description "Use the ifconfig resource to manage interfaces on Unix and Linux systems."
+      description "Use the **ifconfig** resource to manage interfaces on Unix and Linux systems."
 
       state_attrs :inet_addr, :mask
 
diff --git a/lib/chef/resource/ips_package.rb b/lib/chef/resource/ips_package.rb
index 4a6c745b8c..a579a5a5a2 100644
--- a/lib/chef/resource/ips_package.rb
+++ b/lib/chef/resource/ips_package.rb
@@ -27,7 +27,7 @@ class Chef
       provides :ips_package
       provides :package, os: "solaris2"
 
-      description "Use the ips_package resource to manage packages (using Image Packaging System (IPS)) on the Solaris 11 platform."
+      description "Use the **ips_package** resource to manage packages (using Image Packaging System (IPS)) on the Solaris 11 platform."
 
       allowed_actions :install, :remove, :upgrade
 
diff --git a/lib/chef/resource/kernel_module.rb b/lib/chef/resource/kernel_module.rb
index ab377600a0..c3b3dba9d5 100644
--- a/lib/chef/resource/kernel_module.rb
+++ b/lib/chef/resource/kernel_module.rb
@@ -15,7 +15,7 @@ class Chef
 
       provides :kernel_module
 
-      description "Use the kernel_module resource to manage kernel modules on Linux systems. This resource can load, unload, blacklist, disable, install, and uninstall modules."
+      description "Use the **kernel_module** resource to manage kernel modules on Linux systems. This resource can load, unload, blacklist, disable, install, and uninstall modules."
       introduced "14.3"
       examples <<~DOC
         Install and load a kernel module, and ensure it loads on reboot.
diff --git a/lib/chef/resource/ksh.rb b/lib/chef/resource/ksh.rb
index ea946049e0..90f1a784c9 100644
--- a/lib/chef/resource/ksh.rb
+++ b/lib/chef/resource/ksh.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :ksh
 
-      description "Use the ksh resource to execute scripts using the Korn shell (ksh)"\
+      description "Use the **ksh** resource to execute scripts using the Korn shell (ksh)"\
                   " interpreter. This resource may also use any of the actions and properties"\
                   " that are available to the execute resource. Commands that are executed"\
                   " with this resource are (by their nature) not idempotent, as they are"\
diff --git a/lib/chef/resource/launchd.rb b/lib/chef/resource/launchd.rb
index 613ea415d2..e116f8c624 100644
--- a/lib/chef/resource/launchd.rb
+++ b/lib/chef/resource/launchd.rb
@@ -24,7 +24,7 @@ class Chef
       unified_mode true
       provides :launchd
 
-      description "Use the launchd resource to manage system-wide services (daemons) and per-user services (agents) on the macOS platform."
+      description "Use the **launchd** resource to manage system-wide services (daemons) and per-user services (agents) on the macOS platform."
       introduced "12.8"
 
       default_action :create
diff --git a/lib/chef/resource/link.rb b/lib/chef/resource/link.rb
index 6c63e7b3cd..e1422d0d61 100644
--- a/lib/chef/resource/link.rb
+++ b/lib/chef/resource/link.rb
@@ -28,14 +28,14 @@ class Chef
 
       provides :link
 
-      description "Use the link resource to create symbolic or hard links.\n\n"\
+      description "Use the **link** resource to create symbolic or hard links.\n\n"\
                   "A symbolic link—sometimes referred to as a soft link—is a directory entry"\
                   " that associates a file name with a string that contains an absolute or"\
-                  " relative path to a file on any file system. In other words, “a file that"\
-                  " contains a path that points to another file.” A symbolic link creates a new"\
+                  " relative path to a file on any file system. In other words, 'a file that"\
+                  " contains a path that points to another file.' A symbolic link creates a new"\
                   " file with a new inode that points to the inode location of the original file.\n\n"\
                   "A hard link is a directory entry that associates a file with another file in the"\
-                  " same file system. In other words, “multiple directory entries to the same file.”"\
+                  " same file system. In other words, 'multiple directory entries to the same file.'"\
                   " A hard link creates a new file that points to the same inode as the original file."
 
       state_attrs :owner # required since it's not a property below
diff --git a/lib/chef/resource/locale.rb b/lib/chef/resource/locale.rb
index 47d11081f1..bb4f6628e2 100644
--- a/lib/chef/resource/locale.rb
+++ b/lib/chef/resource/locale.rb
@@ -24,7 +24,7 @@ class Chef
       unified_mode true
       provides :locale
 
-      description "Use the locale resource to set the system's locale on Debian and Windows systems. Windows support was added in Chef Infra Client 16.0"
+      description "Use the **locale** resource to set the system's locale on Debian and Windows systems. Windows support was added in Chef Infra Client 16.0"
       introduced "14.5"
 
       examples <<~DOC
diff --git a/lib/chef/resource/log.rb b/lib/chef/resource/log.rb
index 6ca856accf..e9f8bc315a 100644
--- a/lib/chef/resource/log.rb
+++ b/lib/chef/resource/log.rb
@@ -33,7 +33,7 @@ class Chef
 
       provides :log, target_mode: true
 
-      description "Use the log resource to create log entries. The log resource behaves"\
+      description "Use the **log** resource to create log entries. The log resource behaves"\
                   " like any other resource: built into the resource collection during the"\
                   " compile phase, and then run during the execution phase. (To create a log"\
                   " entry that is not built into the resource collection, use Chef::Log instead"\
diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb
index 2c3bca735b..acd783cade 100644
--- a/lib/chef/resource/macos_userdefaults.rb
+++ b/lib/chef/resource/macos_userdefaults.rb
@@ -26,7 +26,7 @@ class Chef
       provides(:macos_userdefaults) { true }
       provides(:mac_os_x_userdefaults) { true }
 
-      description "Use the macos_userdefaults resource to manage the macOS user defaults system. The properties of this resource are passed to the defaults command, and the parameters follow the convention of that command. See the defaults(1) man page for details on how the tool works."
+      description "Use the **macos_userdefaults** resource to manage the macOS user defaults system. The properties of this resource are passed to the defaults command, and the parameters follow the convention of that command. See the defaults(1) man page for details on how the tool works."
       introduced "14.0"
 
       property :domain, String,
diff --git a/lib/chef/resource/macosx_service.rb b/lib/chef/resource/macosx_service.rb
index c3a4588b5b..693b8a4b87 100644
--- a/lib/chef/resource/macosx_service.rb
+++ b/lib/chef/resource/macosx_service.rb
@@ -26,7 +26,7 @@ class Chef
       provides :macosx_service
       provides :service, os: "darwin"
 
-      description "Use the macosx_service resource to manage services on the macOS platform."
+      description "Use the **macosx_service** resource to manage services on the macOS platform."
 
       property :plist, String,
         description: "A plist to use in the case where the filename and label for the service do not match."
diff --git a/lib/chef/resource/macports_package.rb b/lib/chef/resource/macports_package.rb
index acc10900f4..70fa84dec7 100644
--- a/lib/chef/resource/macports_package.rb
+++ b/lib/chef/resource/macports_package.rb
@@ -24,7 +24,7 @@ class Chef
       unified_mode true
       provides :macports_package
 
-      description "Use the macports_package resource to manage packages for the macOS platform using the MacPorts package management system."
+      description "Use the **macports_package** resource to manage packages for the macOS platform using the MacPorts package management system."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index ab5e074c04..7c1d066488 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :mdadm
 
-      description "Use the mdadm resource to manage RAID devices in a Linux environment using the mdadm utility. The mdadm resource"\
+      description "Use the **mdadm** resource to manage RAID devices in a Linux environment using the mdadm utility. The mdadm resource"\
                   " will create and assemble an array, but it will not create the config file that is used to persist the array upon"\
                   " reboot. If the config file is required, it must be done by specifying a template with the correct array layout,"\
                   " and then by using the mount provider to create a file systems table (fstab) entry."
diff --git a/lib/chef/resource/mount.rb b/lib/chef/resource/mount.rb
index f717f90372..5154cac3d9 100644
--- a/lib/chef/resource/mount.rb
+++ b/lib/chef/resource/mount.rb
@@ -22,7 +22,7 @@ require_relative "../resource"
 class Chef
   class Resource
     class Mount < Chef::Resource
-      description "Use the mount resource to manage a mounted file system."
+      description "Use the **mount** resource to manage a mounted file system."
       unified_mode true
 
       provides :mount
diff --git a/lib/chef/resource/msu_package.rb b/lib/chef/resource/msu_package.rb
index 0ef7908515..088e0e06f1 100644
--- a/lib/chef/resource/msu_package.rb
+++ b/lib/chef/resource/msu_package.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides :msu_package
 
-      description "Use the msu_package resource to install Microsoft Update(MSU) packages on Microsoft Windows machines."
+      description "Use the **msu_package** resource to install Microsoft Update(MSU) packages on Microsoft Windows machines."
       introduced "12.17"
 
       allowed_actions :install, :remove
diff --git a/lib/chef/resource/ohai.rb b/lib/chef/resource/ohai.rb
index e5314829a7..93fdb82676 100644
--- a/lib/chef/resource/ohai.rb
+++ b/lib/chef/resource/ohai.rb
@@ -29,7 +29,7 @@ class Chef
 
       provides :ohai
 
-      description "Use the ohai resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the #{Chef::Dist::CLIENT} run."
+      description "Use the **ohai** resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the #{Chef::Dist::CLIENT} run."
 
       property :plugin, String,
         description: "The name of an Ohai plugin to be reloaded. If this property is not specified, #{Chef::Dist::PRODUCT} will reload all plugins."
diff --git a/lib/chef/resource/ohai_hint.rb b/lib/chef/resource/ohai_hint.rb
index acc307b17a..2c962f0957 100644
--- a/lib/chef/resource/ohai_hint.rb
+++ b/lib/chef/resource/ohai_hint.rb
@@ -24,7 +24,7 @@ class Chef
 
       provides(:ohai_hint) { true }
 
-      description "Use the ohai_hint resource to aid in configuration detection by passing hint data to Ohai."
+      description "Use the **ohai_hint** resource to aid in configuration detection by passing hint data to Ohai."
       introduced "14.0"
 
       property :hint_name, String,
diff --git a/lib/chef/resource/openbsd_package.rb b/lib/chef/resource/openbsd_package.rb
index 645aea12c8..af632ebb57 100644
--- a/lib/chef/resource/openbsd_package.rb
+++ b/lib/chef/resource/openbsd_package.rb
@@ -29,7 +29,7 @@ class Chef
       provides :openbsd_package
       provides :package, os: "openbsd"
 
-      description "Use the openbsd_package resource to manage packages for the OpenBSD platform."
+      description "Use the **openbsd_package** resource to manage packages for the OpenBSD platform."
       introduced "12.1"
 
       property :package_name, String,
diff --git a/lib/chef/resource/openssl_dhparam.rb b/lib/chef/resource/openssl_dhparam.rb
index 68210173c0..6b85ea8fea 100644
--- a/lib/chef/resource/openssl_dhparam.rb
+++ b/lib/chef/resource/openssl_dhparam.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides(:openssl_dhparam) { true }
 
-      description "Use the openssl_dhparam resource to generate dhparam.pem files. If a valid dhparam.pem file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid dhparam file, it will be overwritten."
+      description "Use the **openssl_dhparam** resource to generate dhparam.pem files. If a valid dhparam.pem file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid dhparam file, it will be overwritten."
       introduced "14.0"
       examples <<~DOC
         Create a 1024bit dhparam file
diff --git a/lib/chef/resource/openssl_ec_private_key.rb b/lib/chef/resource/openssl_ec_private_key.rb
index 888d02bc64..fcf7980166 100644
--- a/lib/chef/resource/openssl_ec_private_key.rb
+++ b/lib/chef/resource/openssl_ec_private_key.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :openssl_ec_private_key
 
-      description "Use the openssl_ec_private_key resource to generate an elliptic curve (EC) private key file. If a valid EC key file can be opened at the specified location, no new file will be created. If the EC key file cannot be opened, either because it does not exist or because the password to the EC key file does not match the password in the recipe, then it will be overwritten."
+      description "Use the **openssl_ec_private_key** resource to generate an elliptic curve (EC) private key file. If a valid EC key file can be opened at the specified location, no new file will be created. If the EC key file cannot be opened, either because it does not exist or because the password to the EC key file does not match the password in the recipe, then it will be overwritten."
       introduced "14.4"
       examples <<~DOC
         Generate a new ec privatekey with prime256v1 key curve and default des3 cipher
diff --git a/lib/chef/resource/openssl_ec_public_key.rb b/lib/chef/resource/openssl_ec_public_key.rb
index b3b739a8be..bff0754fc9 100644
--- a/lib/chef/resource/openssl_ec_public_key.rb
+++ b/lib/chef/resource/openssl_ec_public_key.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :openssl_ec_public_key
 
-      description "Use the openssl_ec_public_key resource to generate elliptic curve (EC) public key files from a given EC private key."
+      description "Use the **openssl_ec_public_key** resource to generate elliptic curve (EC) public key files from a given EC private key."
       introduced "14.4"
       examples <<~DOC
         Generate new ec public key from a private key on disk
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index 6db73c6b54..ff1d7ae426 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -26,7 +26,7 @@ class Chef
       provides(:openssl_rsa_private_key) { true }
       provides(:openssl_rsa_key) { true } # legacy cookbook resource name
 
-      description "Use the openssl_rsa_private_key resource to generate RSA private key files. If a valid RSA key file can be opened at the specified location, no new file will be created. If the RSA key file cannot be opened, either because it does not exist or because the password to the RSA key file does not match the password in the recipe, it will be overwritten."
+      description "Use the **openssl_rsa_private_key** resource to generate RSA private key files. If a valid RSA key file can be opened at the specified location, no new file will be created. If the RSA key file cannot be opened, either because it does not exist or because the password to the RSA key file does not match the password in the recipe, it will be overwritten."
       introduced "14.0"
       examples <<~DOC
         Generate new 2048bit key with the default des3 cipher
diff --git a/lib/chef/resource/openssl_rsa_public_key.rb b/lib/chef/resource/openssl_rsa_public_key.rb
index a3ccfd8f9f..56e7f1e032 100644
--- a/lib/chef/resource/openssl_rsa_public_key.rb
+++ b/lib/chef/resource/openssl_rsa_public_key.rb
@@ -47,7 +47,7 @@ class Chef
         ```
       DOC
 
-      description "Use the openssl_rsa_public_key resource to generate RSA public key files for a given RSA private key."
+      description "Use the **openssl_rsa_public_key** resource to generate RSA public key files for a given RSA private key."
       introduced "14.0"
 
       property :path, String,
diff --git a/lib/chef/resource/openssl_x509_certificate.rb b/lib/chef/resource/openssl_x509_certificate.rb
index b064c87476..a81b50d9b9 100644
--- a/lib/chef/resource/openssl_x509_certificate.rb
+++ b/lib/chef/resource/openssl_x509_certificate.rb
@@ -27,7 +27,7 @@ class Chef
       provides :openssl_x509_certificate
       provides(:openssl_x509) { true } # legacy cookbook name.
 
-      description "Use the openssl_x509_certificate resource to generate signed or self-signed, PEM-formatted x509 certificates. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate. If a CA private key and certificate are provided, the certificate will be signed with them. Note: This resource was renamed from openssl_x509 to openssl_x509_certificate. The legacy name will continue to function, but cookbook code should be updated for the new resource name."
+      description "Use the **openssl_x509_certificate** resource to generate signed or self-signed, PEM-formatted x509 certificates. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate. If a CA private key and certificate are provided, the certificate will be signed with them. Note: This resource was renamed from openssl_x509 to openssl_x509_certificate. The legacy name will continue to function, but cookbook code should be updated for the new resource name."
       introduced "14.4"
       examples <<~DOC
         Create a simple self-signed certificate file
diff --git a/lib/chef/resource/openssl_x509_crl.rb b/lib/chef/resource/openssl_x509_crl.rb
index 5740e06a57..0a1abf577f 100644
--- a/lib/chef/resource/openssl_x509_crl.rb
+++ b/lib/chef/resource/openssl_x509_crl.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :openssl_x509_crl
 
-      description "Use the openssl_x509_crl resource to generate PEM-formatted x509 certificate revocation list (CRL) files."
+      description "Use the **openssl_x509_crl** resource to generate PEM-formatted x509 certificate revocation list (CRL) files."
       introduced "14.4"
       examples <<~DOC
         Generate a CRL file given a cert file and key file
diff --git a/lib/chef/resource/openssl_x509_request.rb b/lib/chef/resource/openssl_x509_request.rb
index 8534dedda8..ec0ec2eaba 100644
--- a/lib/chef/resource/openssl_x509_request.rb
+++ b/lib/chef/resource/openssl_x509_request.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :openssl_x509_request
 
-      description "Use the openssl_x509_request resource to generate PEM-formatted x509 certificates requests. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate."
+      description "Use the **openssl_x509_request** resource to generate PEM-formatted x509 certificates requests. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate."
       introduced "14.4"
       examples <<~DOC
         Generate new ec key and csr file
diff --git a/lib/chef/resource/osx_profile.rb b/lib/chef/resource/osx_profile.rb
index 8060db5076..40be334678 100644
--- a/lib/chef/resource/osx_profile.rb
+++ b/lib/chef/resource/osx_profile.rb
@@ -26,7 +26,7 @@ class Chef
       provides :osx_profile
       provides :osx_config_profile
 
-      description "Use the osx_profile resource to manage configuration profiles (.mobileconfig files) on the macOS platform. The osx_profile resource installs profiles by using the uuidgen library to generate a unique ProfileUUID, and then using the profiles command to install the profile on the system."
+      description "Use the **osx_profile** resource to manage configuration profiles (.mobileconfig files) on the macOS platform. The osx_profile resource installs profiles by using the uuidgen library to generate a unique ProfileUUID, and then using the profiles command to install the profile on the system."
       introduced "12.7"
 
       default_action :install
diff --git a/lib/chef/resource/package.rb b/lib/chef/resource/package.rb
index 3325013ff8..db3b12d289 100644
--- a/lib/chef/resource/package.rb
+++ b/lib/chef/resource/package.rb
@@ -25,7 +25,7 @@ class Chef
       unified_mode true
       provides :package
 
-      description "Use the package resource to manage packages. When the package is"\
+      description "Use the **package** resource to manage packages. When the package is"\
                   " installed from a local file (such as with RubyGems, dpkg, or RPM"\
                   " Package Manager), the file must be added to the node using the remote_file"\
                   " or cookbook_file resources.\n\nThis resource is the base resource for"\
diff --git a/lib/chef/resource/pacman_package.rb b/lib/chef/resource/pacman_package.rb
index 9600201905..14856de7dd 100644
--- a/lib/chef/resource/pacman_package.rb
+++ b/lib/chef/resource/pacman_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :pacman_package
 
-      description "Use the pacman_package resource to manage packages (using pacman) on the Arch Linux platform."
+      description "Use the **pacman_package** resource to manage packages (using pacman) on the Arch Linux platform."
     end
   end
 end
diff --git a/lib/chef/resource/paludis_package.rb b/lib/chef/resource/paludis_package.rb
index 1d3fb0f44c..385922c940 100644
--- a/lib/chef/resource/paludis_package.rb
+++ b/lib/chef/resource/paludis_package.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :paludis_package
 
-      description "Use the paludis_package resource to manage packages for the Paludis platform."
+      description "Use the **paludis_package** resource to manage packages for the Paludis platform."
       introduced "12.1"
 
       allowed_actions :install, :remove, :upgrade
diff --git a/lib/chef/resource/perl.rb b/lib/chef/resource/perl.rb
index 1f0cd58fd3..bf8b43429f 100644
--- a/lib/chef/resource/perl.rb
+++ b/lib/chef/resource/perl.rb
@@ -31,7 +31,7 @@ class Chef
         @interpreter = "perl"
       end
 
-      description "Use the perl resource to execute scripts using the Perl interpreter."\
+      description "Use the **perl** resource to execute scripts using the Perl interpreter."\
                   " This resource may also use any of the actions and properties that are"\
                   " available to the execute resource. Commands that are executed with this"\
                   " resource are (by their nature) not idempotent, as they are typically"\
diff --git a/lib/chef/resource/plist.rb b/lib/chef/resource/plist.rb
index ac9c6e237b..944eea18e9 100644
--- a/lib/chef/resource/plist.rb
+++ b/lib/chef/resource/plist.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :plist
 
-      description "Use the plist resource to set config values in plist files on macOS systems."
+      description "Use the **plist** resource to set config values in plist files on macOS systems."
       introduced "16.0"
 
       property :path, String, name_property: true
diff --git a/lib/chef/resource/portage_package.rb b/lib/chef/resource/portage_package.rb
index 28fa1d6217..05f54c9d21 100644
--- a/lib/chef/resource/portage_package.rb
+++ b/lib/chef/resource/portage_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :portage_package
 
-      description "Use the portage_package resource to manage packages for the Gentoo platform."
+      description "Use the **portage_package** resource to manage packages for the Gentoo platform."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/powershell_package.rb b/lib/chef/resource/powershell_package.rb
index b83342c92d..7d013eac4c 100644
--- a/lib/chef/resource/powershell_package.rb
+++ b/lib/chef/resource/powershell_package.rb
@@ -24,7 +24,7 @@ class Chef
 
       provides :powershell_package
 
-      description "Use the powershell_package resource to install and manage packages via the PowerShell Package Manager for the Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be configured in the PowerShell Package Manager via the powershell_package_source resource."
+      description "Use the **powershell_package** resource to install and manage packages via the PowerShell Package Manager for the Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be configured in the PowerShell Package Manager via the powershell_package_source resource."
       introduced "12.16"
 
       allowed_actions :install, :remove
diff --git a/lib/chef/resource/powershell_package_source.rb b/lib/chef/resource/powershell_package_source.rb
index d253de0958..a9af00fe57 100644
--- a/lib/chef/resource/powershell_package_source.rb
+++ b/lib/chef/resource/powershell_package_source.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :powershell_package_source
 
-      description "Use the powershell_package_source resource to register a PowerShell package repository."
+      description "Use the **powershell_package_source** resource to register a PowerShell package repository."
       introduced "14.3"
 
       property :source_name, String,
diff --git a/lib/chef/resource/powershell_script.rb b/lib/chef/resource/powershell_script.rb
index 494636c5bc..434f9ca09f 100644
--- a/lib/chef/resource/powershell_script.rb
+++ b/lib/chef/resource/powershell_script.rb
@@ -39,7 +39,7 @@ class Chef
           end
         }
 
-      description "Use the powershell_script resource to execute a script using the Windows PowerShell"\
+      description "Use the **powershell_script** resource to execute a script using the Windows PowerShell"\
                   " interpreter, much like how the script and script-based resources—bash, csh, perl, python,"\
                   " and ruby—are used. The powershell_script is specific to the Microsoft Windows platform"\
                   " and the Windows PowerShell interpreter.\n\n The powershell_script resource creates and"\
diff --git a/lib/chef/resource/python.rb b/lib/chef/resource/python.rb
index 2c0bf92fb0..6a9974246d 100644
--- a/lib/chef/resource/python.rb
+++ b/lib/chef/resource/python.rb
@@ -30,7 +30,7 @@ class Chef
         @interpreter = "python"
       end
 
-      description "Use the python resource to execute scripts using the Python interpreter."\
+      description "Use the **python** resource to execute scripts using the Python interpreter."\
                   " This resource may also use any of the actions and properties that are available"\
                   " to the execute resource. Commands that are executed with this resource are (by"\
                   " their nature) not idempotent, as they are typically unique to the environment in"\
diff --git a/lib/chef/resource/reboot.rb b/lib/chef/resource/reboot.rb
index 337b627914..38a493cfae 100644
--- a/lib/chef/resource/reboot.rb
+++ b/lib/chef/resource/reboot.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :reboot
 
-      description "Use the reboot resource to reboot a node, a necessary step with some"\
+      description "Use the **reboot** resource to reboot a node, a necessary step with some"\
                   " installations on certain platforms. This resource is supported for use on"\
                   " the Microsoft Windows, macOS, and Linux platforms.\n"\
                   "In using this resource via notifications, it's important to *only* use"\
diff --git a/lib/chef/resource/registry_key.rb b/lib/chef/resource/registry_key.rb
index f2b8298de0..5cce4bd420 100644
--- a/lib/chef/resource/registry_key.rb
+++ b/lib/chef/resource/registry_key.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides(:registry_key) { true }
 
-      description "Use the registry_key resource to create and delete registry keys in Microsoft Windows."
+      description "Use the **registry_key** resource to create and delete registry keys in Microsoft Windows."
       introduced "11.0"
 
       state_attrs :values
diff --git a/lib/chef/resource/remote_directory.rb b/lib/chef/resource/remote_directory.rb
index a46249cc8f..b6dc0b7a98 100644
--- a/lib/chef/resource/remote_directory.rb
+++ b/lib/chef/resource/remote_directory.rb
@@ -29,7 +29,7 @@ class Chef
 
       provides :remote_directory
 
-      description "Use the remote_directory resource to incrementally transfer a directory from a cookbook to a node. The director that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The remote_directory resource will obey file specificity."
+      description "Use the **remote_directory** resource to incrementally transfer a directory from a cookbook to a node. The director that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The remote_directory resource will obey file specificity."
 
       default_action :create
       allowed_actions :create, :create_if_missing, :delete
diff --git a/lib/chef/resource/remote_file.rb b/lib/chef/resource/remote_file.rb
index 909d5084b7..8056cac922 100644
--- a/lib/chef/resource/remote_file.rb
+++ b/lib/chef/resource/remote_file.rb
@@ -31,8 +31,7 @@ class Chef
 
       provides :remote_file
 
-      description "Use the remote_file resource to transfer a file from a remote location"\
-                  " using file specificity. This resource is similar to the file resource."
+      description "Use the **remote_file** resource to transfer a file from a remote location using file specificity. This resource is similar to the file resource."
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/rhsm_errata.rb b/lib/chef/resource/rhsm_errata.rb
index 7d297d805c..7a1e3df325 100644
--- a/lib/chef/resource/rhsm_errata.rb
+++ b/lib/chef/resource/rhsm_errata.rb
@@ -23,9 +23,7 @@ class Chef
       unified_mode true
       provides(:rhsm_errata) { true }
 
-      description "Use the rhsm_errata resource to install packages associated with a given Red"\
-                  " Hat Subscription Manager Errata ID. This is helpful if packages"\
-                  " to mitigate a single vulnerability must be installed on your hosts."
+      description "Use the **rhsm_errata** resource to install packages associated with a given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate a single vulnerability must be installed on your hosts."
       introduced "14.0"
 
       property :errata_id, String,
diff --git a/lib/chef/resource/rhsm_errata_level.rb b/lib/chef/resource/rhsm_errata_level.rb
index 094af8fc25..9ac3944153 100644
--- a/lib/chef/resource/rhsm_errata_level.rb
+++ b/lib/chef/resource/rhsm_errata_level.rb
@@ -23,7 +23,7 @@ class Chef
       unified_mode true
       provides(:rhsm_errata_level) { true }
 
-      description "Use the rhsm_errata_level resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed."
+      description "Use the **rhsm_errata_level** resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed."
       introduced "14.0"
 
       property :errata_level, String,
diff --git a/lib/chef/resource/rhsm_register.rb b/lib/chef/resource/rhsm_register.rb
index 4ded5e33a7..7188cecbad 100644
--- a/lib/chef/resource/rhsm_register.rb
+++ b/lib/chef/resource/rhsm_register.rb
@@ -25,8 +25,7 @@ class Chef
       unified_mode true
       provides(:rhsm_register) { true }
 
-      description "Use the rhsm_register resource to register a node with the Red Hat Subscription Manager"\
-                  " or a local Red Hat Satellite server."
+      description "Use the **rhsm_register** resource to register a node with the Red Hat Subscription Manager or a local Red Hat Satellite server."
       introduced "14.0"
 
       property :activation_key, [String, Array],
diff --git a/lib/chef/resource/rhsm_repo.rb b/lib/chef/resource/rhsm_repo.rb
index dd67fc60d5..d8959695cf 100644
--- a/lib/chef/resource/rhsm_repo.rb
+++ b/lib/chef/resource/rhsm_repo.rb
@@ -24,8 +24,7 @@ class Chef
 
       provides(:rhsm_repo) { true }
 
-      description "Use the rhsm_repo resource to enable or disable Red Hat Subscription Manager"\
-                  " repositories that are made available via attached subscriptions."
+      description "Use the **rhsm_repo** resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions."
       introduced "14.0"
 
       property :repo_name, String,
diff --git a/lib/chef/resource/rhsm_subscription.rb b/lib/chef/resource/rhsm_subscription.rb
index f2fd5c8a27..15a4822ecd 100644
--- a/lib/chef/resource/rhsm_subscription.rb
+++ b/lib/chef/resource/rhsm_subscription.rb
@@ -24,9 +24,7 @@ class Chef
 
       provides(:rhsm_subscription) { true }
 
-      description "Use the rhsm_subscription resource to add or remove Red Hat Subscription Manager"\
-                  " subscriptions from your host. This can be used when a host's activation_key"\
-                  " does not attach all necessary subscriptions to your host."
+      description "Use the **rhsm_subscription** resource to add or remove Red Hat Subscription Manager subscriptions from your host. This can be used when a host's activation_key does not attach all necessary subscriptions to your host."
       introduced "14.0"
 
       property :pool_id, String,
diff --git a/lib/chef/resource/route.rb b/lib/chef/resource/route.rb
index 0d9d9d431c..9df2031dcb 100644
--- a/lib/chef/resource/route.rb
+++ b/lib/chef/resource/route.rb
@@ -29,7 +29,7 @@ class Chef
       default_action :add
       allowed_actions :add, :delete
 
-      description "Use the route resource to manage the system routing table in a Linux environment."
+      description "Use the **route** resource to manage the system routing table in a Linux environment."
 
       property :target, String,
         description: "The IP address of the target route.",
diff --git a/lib/chef/resource/rpm_package.rb b/lib/chef/resource/rpm_package.rb
index b944142dcb..bd5eabeefb 100644
--- a/lib/chef/resource/rpm_package.rb
+++ b/lib/chef/resource/rpm_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :rpm_package
 
-      description "Use the rpm_package resource to manage packages using the RPM Package Manager."
+      description "Use the **rpm_package** resource to manage packages using the RPM Package Manager."
 
       property :allow_downgrade, [ true, false ], default: true, desired_state: false
 
diff --git a/lib/chef/resource/ruby.rb b/lib/chef/resource/ruby.rb
index f3835f44d4..43e861318e 100644
--- a/lib/chef/resource/ruby.rb
+++ b/lib/chef/resource/ruby.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :ruby
 
-      description "Use the ruby resource to execute scripts using the Ruby interpreter. This"\
+      description "Use the **ruby** resource to execute scripts using the Ruby interpreter. This"\
                   " resource may also use any of the actions and properties that are available"\
                   " to the execute resource. Commands that are executed with this resource are (by"\
                   " their nature) not idempotent, as they are typically unique to the environment"\
diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb
index 5e60579d0c..1fcebe090a 100644
--- a/lib/chef/resource/ruby_block.rb
+++ b/lib/chef/resource/ruby_block.rb
@@ -28,10 +28,7 @@ class Chef
 
       provides :ruby_block, target_mode: true
 
-      description "Use the ruby_block resource to execute Ruby code during a #{Chef::Dist::PRODUCT} run."\
-                  " Ruby code in the ruby_block resource is evaluated with other resources during"\
-                  " convergence, whereas Ruby code outside of a ruby_block resource is evaluated"\
-                  " before other resources, as the recipe is compiled."
+      description "Use the **ruby_block** resource to execute Ruby code during a #{Chef::Dist::PRODUCT} run. Ruby code in the ruby_block resource is evaluated with other resources during convergence, whereas Ruby code outside of a ruby_block resource is evaluated before other resources, as the recipe is compiled."
 
       default_action :run
       allowed_actions :create, :run
diff --git a/lib/chef/resource/scm/git.rb b/lib/chef/resource/scm/git.rb
index 788eafbd3b..c399f9fb24 100644
--- a/lib/chef/resource/scm/git.rb
+++ b/lib/chef/resource/scm/git.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides :git
 
-      description "Use the git resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
+      description "Use the **git** resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
 
       property :additional_remotes, Hash,
         description: "A Hash of additional remotes that are added to the git repository configuration.",
diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb
index 619df673b4..328a49072b 100644
--- a/lib/chef/resource/scm/subversion.rb
+++ b/lib/chef/resource/scm/subversion.rb
@@ -28,7 +28,7 @@ class Chef
 
       provides :subversion
 
-      description "Use the subversion resource to manage source control resources that exist in a Subversion repository."
+      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
 
       allowed_actions :force_export
 
diff --git a/lib/chef/resource/script.rb b/lib/chef/resource/script.rb
index f7e1a013ef..93e30c6a0e 100644
--- a/lib/chef/resource/script.rb
+++ b/lib/chef/resource/script.rb
@@ -28,7 +28,7 @@ class Chef
 
       identity_attr :name
 
-      description "Use the script resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby."\
+      description "Use the **script** resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby."\
                   " This resource may also use any of the actions and properties that are available to the execute resource. Commands"\
                   " that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the"\
                   " environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
diff --git a/lib/chef/resource/service.rb b/lib/chef/resource/service.rb
index 2a55973500..08bf6cd5bc 100644
--- a/lib/chef/resource/service.rb
+++ b/lib/chef/resource/service.rb
@@ -31,7 +31,7 @@ class Chef
 
       provides :service, target_mode: true
 
-      description "Use the service resource to manage a service."
+      description "Use the **service** resource to manage a service."
 
       default_action :nothing
       allowed_actions :enable, :disable, :start, :stop, :restart, :reload,
diff --git a/lib/chef/resource/smartos_package.rb b/lib/chef/resource/smartos_package.rb
index eb37b804d5..08b2f0d82f 100644
--- a/lib/chef/resource/smartos_package.rb
+++ b/lib/chef/resource/smartos_package.rb
@@ -26,7 +26,7 @@ class Chef
       provides :smartos_package
       provides :package, platform_family: "smartos"
 
-      description "Use the smartos_package resource to manage packages for the SmartOS platform."
+      description "Use the **smartos_package** resource to manage packages for the SmartOS platform."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/snap_package.rb b/lib/chef/resource/snap_package.rb
index 933c3fdcb5..c211b03555 100644
--- a/lib/chef/resource/snap_package.rb
+++ b/lib/chef/resource/snap_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :snap_package
 
-      description "Use the snap_package resource to manage snap packages on Debian and Ubuntu platforms."
+      description "Use the **snap_package** resource to manage snap packages on Debian and Ubuntu platforms."
       introduced "15.0"
 
       property :channel, String,
diff --git a/lib/chef/resource/ssh_known_hosts_entry.rb b/lib/chef/resource/ssh_known_hosts_entry.rb
index f2154307d8..95a1b75644 100644
--- a/lib/chef/resource/ssh_known_hosts_entry.rb
+++ b/lib/chef/resource/ssh_known_hosts_entry.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides :ssh_known_hosts_entry
 
-      description "Use the ssh_known_hosts_entry resource to add an entry for the specified host in /etc/ssh/ssh_known_hosts or a user's known hosts file if specified."
+      description "Use the **ssh_known_hosts_entry** resource to add an entry for the specified host in /etc/ssh/ssh_known_hosts or a user's known hosts file if specified."
       introduced "14.3"
 
       property :host, String,
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index 5dbb60e656..159291f41e 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -28,7 +28,7 @@ class Chef
 
       provides(:sudo) { true }
 
-      description "Use the sudo resource to add or remove individual sudo entries using sudoers.d files."\
+      description "Use the **sudo** resource to add or remove individual sudo entries using sudoers.d files."\
                   " Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the"\
                   " '#includedir' directive introduced in version 1.7.2. This resource does not enforce"\
                   " installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian,"\
diff --git a/lib/chef/resource/swap_file.rb b/lib/chef/resource/swap_file.rb
index 2d76b0fac4..a39a05080d 100644
--- a/lib/chef/resource/swap_file.rb
+++ b/lib/chef/resource/swap_file.rb
@@ -24,7 +24,7 @@ class Chef
 
       provides(:swap_file) { true }
 
-      description "Use the swap_file resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host."
+      description "Use the **swap_file** resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host."
       introduced "14.0"
 
       property :path, String,
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index 562344b000..c2ac8224b4 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -25,7 +25,7 @@ class Chef
       provides(:sysctl) { true }
       provides(:sysctl_param) { true }
 
-      description "Use the sysctl resource to set or remove kernel parameters using the sysctl"\
+      description "Use the **sysctl** resource to set or remove kernel parameters using the sysctl"\
                   " command line tool and configuration files in the system's sysctl.d directory. "\
                   "Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If"\
                   " an existing value was already set for the value it will be backed up to the node"\
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index 9e7067bd70..031b58f3a7 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides(:systemd_unit) { true }
 
-      description "Use the systemd_unit resource to create, manage, and run systemd units."
+      description "Use the **systemd_unit** resource to create, manage, and run systemd units."
       introduced "12.11"
 
       default_action :nothing
diff --git a/lib/chef/resource/timezone.rb b/lib/chef/resource/timezone.rb
index 081d65e9bf..a7813ce9c2 100644
--- a/lib/chef/resource/timezone.rb
+++ b/lib/chef/resource/timezone.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :timezone
 
-      description "Use the timezone resource to change the system timezone on Windows, Linux, and macOS hosts. Timezones are specified in tz database format, with a complete list of available TZ values for Linux and macOS here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones and for Windows here: https://ss64.com/nt/timezones.html."
+      description "Use the **timezone** resource to change the system timezone on Windows, Linux, and macOS hosts. Timezones are specified in tz database format, with a complete list of available TZ values for Linux and macOS here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones and for Windows here: https://ss64.com/nt/timezones.html."
       introduced "14.6"
 
       property :timezone, String,
diff --git a/lib/chef/resource/user.rb b/lib/chef/resource/user.rb
index 6f96cac980..408932175d 100644
--- a/lib/chef/resource/user.rb
+++ b/lib/chef/resource/user.rb
@@ -23,7 +23,7 @@ class Chef
     class User < Chef::Resource
       unified_mode true
 
-      description "Use the user resource to add users, update existing users, remove users, and to lock/unlock user passwords."
+      description "Use the **user** resource to add users, update existing users, remove users, and to lock/unlock user passwords."
 
       default_action :create
       allowed_actions :create, :remove, :modify, :manage, :lock, :unlock
diff --git a/lib/chef/resource/user_ulimit.rb b/lib/chef/resource/user_ulimit.rb
index 3a0ea18694..5b5c887de1 100644
--- a/lib/chef/resource/user_ulimit.rb
+++ b/lib/chef/resource/user_ulimit.rb
@@ -26,32 +26,34 @@ class Chef
 
       provides :user_ulimit
 
+      description "Use the **user_ulimit** resource to create individual ulimit files that are installed into the `/etc/security/limits.d/` directory."
       introduced "16.0"
-      description "Use the user_ulimit resource to create individual ulimit files that are installed into the `/etc/security/limits.d/` directory."
       examples <<~DOC
-        set filehandle limit for the tomcat user
-        ```ruby
-        user_ulimit 'tomcat' do
-          filehandle_limit 8192
-        end
-        ```
+      **Set filehandle limit for the tomcat user**:
 
-        specify a username that differs from the name given to the resource block
-        ```ruby
-        user_ulimit 'Bump filehandle limits for tomcat user' do
-          username 'tomcat'
-          filehandle_limit 8192
-        end
-        ```
+      ```ruby
+      user_ulimit 'tomcat' do
+        filehandle_limit 8192
+      end
+      ```
 
-        specify a non-default filename
-        set filehandle limit for the tomcat user
-        ```ruby
-        user_ulimit 'tomcat' do
-          filehandle_limit 8192
-          filename 'tomcat_filehandle_limits.conf'
-        end
-        ```
+      **Specify a username that differs from the name given to the resource block**:
+
+      ```ruby
+      user_ulimit 'Bump filehandle limits for tomcat user' do
+        username 'tomcat'
+        filehandle_limit 8192
+      end
+      ```
+
+      **Set filehandle limit for the tomcat user with a non-default filename**:
+
+      ```ruby
+      user_ulimit 'tomcat' do
+        filehandle_limit 8192
+        filename 'tomcat_filehandle_limits.conf'
+      end
+      ```
       DOC
 
       property :username, String, name_property: true
diff --git a/lib/chef/resource/windows_ad_join.rb b/lib/chef/resource/windows_ad_join.rb
index 16c40a70ef..b0b6824f88 100644
--- a/lib/chef/resource/windows_ad_join.rb
+++ b/lib/chef/resource/windows_ad_join.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsAdJoin < Chef::Resource
       provides :windows_ad_join
 
-      description "Use the windows_ad_join resource to join a Windows Active Directory domain."
+      description "Use the **windows_ad_join** resource to join a Windows Active Directory domain."
       introduced "14.0"
 
       property :domain_name, String,
diff --git a/lib/chef/resource/windows_auto_run.rb b/lib/chef/resource/windows_auto_run.rb
index 63af080191..1b3de8a68c 100644
--- a/lib/chef/resource/windows_auto_run.rb
+++ b/lib/chef/resource/windows_auto_run.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsAutorun < Chef::Resource
       provides(:windows_auto_run) { true }
 
-      description "Use the windows_auto_run resource to set applications to run at login."
+      description "Use the **windows_auto_run** resource to set applications to run at login."
       introduced "14.0"
 
       property :program_name, String,
diff --git a/lib/chef/resource/windows_certificate.rb b/lib/chef/resource/windows_certificate.rb
index 7bf433538a..cfe119e97a 100644
--- a/lib/chef/resource/windows_certificate.rb
+++ b/lib/chef/resource/windows_certificate.rb
@@ -28,7 +28,7 @@ class Chef
     class WindowsCertificate < Chef::Resource
       provides :windows_certificate
 
-      description "Use the windows_certificate resource to install a certificate into the Windows certificate store from a file. The resource grants read-only access to the private key for designated accounts. Due to current limitations in WinRM, installing certificates remotely may not work if the operation requires a user profile. Operations on the local machine store should still work."
+      description "Use the **windows_certificate** resource to install a certificate into the Windows certificate store from a file. The resource grants read-only access to the private key for designated accounts. Due to current limitations in WinRM, installing certificates remotely may not work if the operation requires a user profile. Operations on the local machine store should still work."
       introduced "14.7"
 
       property :source, String,
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index 8f551df9f9..e5dd892a9e 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -25,7 +25,7 @@ class Chef
       provides :windows_env
       provides :env # backwards compat with the pre-Chef 14 resource name
 
-      description "Use the windows_env resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
 
       default_action :create
       allowed_actions :create, :delete, :modify
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index 4a4179f944..e243eb365e 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsFeature < Chef::Resource
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
+      description "Use the **windows_feature** resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
diff --git a/lib/chef/resource/windows_feature_dism.rb b/lib/chef/resource/windows_feature_dism.rb
index 276eb9cb1f..7b0206f96b 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -24,7 +24,7 @@ class Chef
     class WindowsFeatureDism < Chef::Resource
       provides(:windows_feature_dism) { true }
 
-      description "Use the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM."
+      description "Use the **windows_feature_dism** resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
 
       property :feature_name, [Array, String],
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index 522ffcf4a7..ac33dfa0a3 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -25,7 +25,7 @@ class Chef
     class WindowsFeaturePowershell < Chef::Resource
       provides(:windows_feature_powershell) { true }
 
-      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
+      description "Use the **windows_feature_powershell** resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
diff --git a/lib/chef/resource/windows_firewall_rule.rb b/lib/chef/resource/windows_firewall_rule.rb
index 0ba4c60a46..f7f22856d6 100644
--- a/lib/chef/resource/windows_firewall_rule.rb
+++ b/lib/chef/resource/windows_firewall_rule.rb
@@ -26,10 +26,11 @@ class Chef
     class WindowsFirewallRule < Chef::Resource
       provides :windows_firewall_rule
 
-      description "Use the windows_firewall_rule resource to create, change or remove Windows firewall rules."
+      description "Use the **windows_firewall_rule** resource to create, change or remove Windows firewall rules."
       introduced "14.7"
       examples <<~DOC
-      Allowing port 80 access
+      **Allowing port 80 access**:
+
       ```ruby
       windows_firewall_rule 'IIS' do
         local_port '80'
@@ -38,7 +39,8 @@ class Chef
       end
       ```
 
-      Allow protocol ICMPv6 with ICMP Type
+      **Allow protocol ICMPv6 with ICMP Type**:
+
       ```ruby
       windows_firewall_rule 'CoreNet-Rule' do
         rule_name 'CoreNet-ICMP6-LR2-In'
@@ -49,7 +51,8 @@ class Chef
       end
       ```
 
-      Blocking WinRM over HTTP on a particular IP
+      **Blocking WinRM over HTTP on a particular IP**:
+
       ```ruby
       windows_firewall_rule 'Disable WinRM over HTTP' do
         local_port '5985'
@@ -59,7 +62,8 @@ class Chef
       end
       ```
 
-      Deleting an existing rule
+      **Deleting an existing rule**
+
       ```ruby
       windows_firewall_rule 'Remove the SSH rule' do
         rule_name 'ssh'
diff --git a/lib/chef/resource/windows_font.rb b/lib/chef/resource/windows_font.rb
index b078422bf3..dfb73f8a75 100644
--- a/lib/chef/resource/windows_font.rb
+++ b/lib/chef/resource/windows_font.rb
@@ -24,7 +24,7 @@ class Chef
 
       provides(:windows_font) { true }
 
-      description "Use the windows_font resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
+      description "Use the **windows_font** resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
       introduced "14.0"
 
       property :font_name, String,
diff --git a/lib/chef/resource/windows_package.rb b/lib/chef/resource/windows_package.rb
index b0af2c6aef..27379da1a3 100644
--- a/lib/chef/resource/windows_package.rb
+++ b/lib/chef/resource/windows_package.rb
@@ -30,7 +30,7 @@ class Chef
       provides(:windows_package) { true }
       provides :package, os: "windows"
 
-      description "Use the windows_package resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
+      description "Use the **windows_package** resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
       introduced "11.12"
 
       allowed_actions :install, :remove
diff --git a/lib/chef/resource/windows_pagefile.rb b/lib/chef/resource/windows_pagefile.rb
index c43838b932..d49e85eec8 100644
--- a/lib/chef/resource/windows_pagefile.rb
+++ b/lib/chef/resource/windows_pagefile.rb
@@ -22,7 +22,7 @@ class Chef
     class WindowsPagefile < Chef::Resource
       provides(:windows_pagefile) { true }
 
-      description "Use the windows_pagefile resource to configure pagefile settings on Windows."
+      description "Use the **windows_pagefile** resource to configure pagefile settings on Windows."
       introduced "14.0"
 
       property :path, String,
diff --git a/lib/chef/resource/windows_path.rb b/lib/chef/resource/windows_path.rb
index f8c014632c..70364eadff 100644
--- a/lib/chef/resource/windows_path.rb
+++ b/lib/chef/resource/windows_path.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsPath < Chef::Resource
       provides(:windows_path) { true }
 
-      description "Use the windows_path resource to manage the path environment variable on Microsoft Windows."
+      description "Use the **windows_path** resource to manage the path environment variable on Microsoft Windows."
       introduced "13.4"
 
       allowed_actions :add, :remove
diff --git a/lib/chef/resource/windows_printer.rb b/lib/chef/resource/windows_printer.rb
index d1b1538f6e..868598374d 100644
--- a/lib/chef/resource/windows_printer.rb
+++ b/lib/chef/resource/windows_printer.rb
@@ -26,11 +26,11 @@ class Chef
 
       provides(:windows_printer) { true }
 
-      description "Use the windows_printer resource to setup Windows printers. Note that this doesn't currently install a printer driver. You must already have the driver installed on the system."
+      description "Use the **windows_printer** resource to setup Windows printers. Note that this doesn't currently install a printer driver. You must already have the driver installed on the system."
       introduced "14.0"
 
       property :device_id, String,
-        description: "An optional property to set the printer queue name if it differs from the resource block's name. Example: 'HP LJ 5200 in fifth floor copy room'.",
+        description: "An optional property to set the printer queue name if it differs from the resource block's name. Example: `HP LJ 5200 in fifth floor copy room`.",
         name_property: true
 
       property :comment, String,
@@ -45,7 +45,7 @@ class Chef
         required: true
 
       property :location, String,
-        description: "Printer location, such as 'Fifth floor copy room'."
+        description: "Printer location, such as `Fifth floor copy room`."
 
       property :shared, [TrueClass, FalseClass],
         description: "Determines whether or not the printer is shared.",
@@ -55,8 +55,8 @@ class Chef
         description: "The name used to identify the shared printer."
 
       property :ipv4_address, String,
-        description: "The IPv4 address of the printer, such as '10.4.64.23'",
-        validation_message: "The ipv4_address property must be in the IPv4 format of WWW.XXX.YYY.ZZZ",
+        description: "The IPv4 address of the printer, such as `10.4.64.23`",
+        validation_message: "The ipv4_address property must be in the IPv4 format of `WWW.XXX.YYY.ZZZ`",
         regex: Resolv::IPv4::Regex
 
       property :exists, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/windows_printer_port.rb b/lib/chef/resource/windows_printer_port.rb
index e51969edfb..faa4d6a708 100644
--- a/lib/chef/resource/windows_printer_port.rb
+++ b/lib/chef/resource/windows_printer_port.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides(:windows_printer_port) { true }
 
-      description "Use the windows_printer_port resource to create and delete TCP/IPv4 printer ports on Windows."
+      description "Use the **windows_printer_port** resource to create and delete TCP/IPv4 printer ports on Windows."
       introduced "14.0"
 
       property :ipv4_address, String,
diff --git a/lib/chef/resource/windows_security_policy.rb b/lib/chef/resource/windows_security_policy.rb
index f048895a67..fdbbc9c0a6 100644
--- a/lib/chef/resource/windows_security_policy.rb
+++ b/lib/chef/resource/windows_security_policy.rb
@@ -40,7 +40,7 @@ class Chef
                 EnableAdminAccount
                 EnableGuestAccount
                 }
-      description "Use the windows_security_policy resource to set a security policy on the Microsoft Windows platform."
+      description "Use the **windows_security_policy** resource to set a security policy on the Microsoft Windows platform."
       introduced "16.0"
 
       property :secoption, String, name_property: true, required: true, equal_to: policy_names,
diff --git a/lib/chef/resource/windows_service.rb b/lib/chef/resource/windows_service.rb
index 3c9a63b86e..defdf9fe29 100644
--- a/lib/chef/resource/windows_service.rb
+++ b/lib/chef/resource/windows_service.rb
@@ -36,7 +36,7 @@ class Chef
       provides(:windows_service) { true }
       provides :service, os: "windows"
 
-      description "Use the windows_service resource to create, delete, or manage a service on the Microsoft Windows platform."
+      description "Use the **windows_service** resource to create, delete, or manage a service on the Microsoft Windows platform."
       introduced "12.0"
 
       allowed_actions :configure_startup, :create, :delete, :configure
diff --git a/lib/chef/resource/windows_share.rb b/lib/chef/resource/windows_share.rb
index 6c29a6443d..1f8586836d 100644
--- a/lib/chef/resource/windows_share.rb
+++ b/lib/chef/resource/windows_share.rb
@@ -28,8 +28,28 @@ class Chef
     class WindowsShare < Chef::Resource
       provides :windows_share
 
-      description "Use the windows_share resource to create, modify and remove Windows shares."
+      description "Use the **windows_share** resource to create, modify and remove Windows shares."
       introduced "14.7"
+      examples <<~DOC
+      **Create a share**:
+
+      ```ruby
+      windows_share 'foo' do
+        action :create
+        path 'C:\\foo'
+        full_users ['DOMAIN_A\\some_user', 'DOMAIN_B\\some_other_user']
+        read_users ['DOMAIN_C\\Domain users']
+      end
+      ```
+
+      **Delete a share**:
+
+      ```ruby
+      windows_share 'foo' do
+        action :delete
+      end
+      ```
+      DOC
 
       # Specifies a name for the SMB share. The name may be composed of any valid file name characters, but must be less than 80 characters long. The names pipe and mailslot are reserved for use by the computer.
       property :share_name, String,
diff --git a/lib/chef/resource/windows_shortcut.rb b/lib/chef/resource/windows_shortcut.rb
index 687c3f167b..e272e89e16 100644
--- a/lib/chef/resource/windows_shortcut.rb
+++ b/lib/chef/resource/windows_shortcut.rb
@@ -23,8 +23,19 @@ class Chef
     class WindowsShortcut < Chef::Resource
       provides(:windows_shortcut) { true }
 
-      description "Use the windows_shortcut resource to create shortcut files on Windows."
+      description "Use the **windows_shortcut** resource to create shortcut files on Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Create a shortcut with a description**:
+
+      ```ruby
+      windows_shortcut 'C:\\shortcut_dir.lnk' do
+        target 'C:\\original_dir'
+        description 'Make a shortcut to C:\\original_dir'
+      end
+      ```
+
+      DOC
 
       property :shortcut_name, String,
         description: "An optional property to set the shortcut name if it differs from the resource block's name.",
@@ -43,7 +54,7 @@ class Chef
         description: "Working directory to use when the target is executed."
 
       property :iconlocation, String,
-        description: "Icon to use for the shortcut. Accepts the format of 'path, index', where index is the icon file to use. See https://msdn.microsoft.com/en-us/library/3s9bx7at.aspx for details"
+        description: "Icon to use for the shortcut. Accepts the format of `path, index`, where index is the icon file to use. See Microsoft's [documentation](https://msdn.microsoft.com/en-us/library/3s9bx7at.aspx) for details"
 
       load_current_value do |desired|
         require "win32ole" if RUBY_PLATFORM =~ /mswin|mingw32|windows/
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index 2a2887ca0a..2a38082539 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -24,8 +24,121 @@ class Chef
     class WindowsTask < Chef::Resource
       provides(:windows_task) { true }
 
-      description "Use the windows_task resource to create, delete or run a Windows scheduled task. Requires Windows Server 2008 or later due to API usage."
+      description "Use the **windows_task** resource to create, delete or run a Windows scheduled task. Requires Windows Server 2008 or later due to API usage."
       introduced "13.0"
+      examples <<~DOC
+      **Create a scheduled task to run every 15 minutes as the Administrator user**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        user 'Administrator'
+        password 'password'
+        command 'chef-client'
+        run_level :highest
+        frequency :minute
+        frequency_modifier 15
+      end
+      ```
+
+      **Create a scheduled task to run every 2 days**:
+
+      ``` ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :daily
+        frequency_modifier 2
+      end
+      ```
+
+      **Create a scheduled task to run on specific days of the week**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        day 'Mon, Thu'
+      end
+      ```
+
+      **Create a scheduled task to run only once**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :once
+        start_time "16:10"
+      end
+      ```
+
+      **Create a scheduled task to run on current day every 3 weeks and delay upto 1 min**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        frequency_modifier 3
+        random_delay '60'
+      end
+      ```
+
+      **Create a scheduled task to run weekly starting on Dec 28th 2018**:
+
+      ```ruby
+      windows_task 'chef-client 8' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        start_day '12/28/2018'
+      end
+      ```
+
+      **Create a scheduled task to run every Monday, Friday every 2 weeks**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        frequency_modifier 2
+        day 'Mon, Fri'
+      end
+      ```
+
+      **Create a scheduled task to run when computer is idle with idle duration 20 min**:
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :on_idle
+        idle_time 20
+      end
+      ```
+
+      **Delete a task named "old task"**:
+      ```ruby
+      windows_task 'old task' do
+        action :delete
+      end
+      ```
+
+      **Enable a task named "chef-client"**:
+      ```ruby
+      windows_task 'chef-client' do
+        action :enable
+      end
+      ```
+
+      **Disable a task named "ProgramDataUpdater" with TaskPath "\\Microsoft\\Windows\\Application Experience\\ProgramDataUpdater"**
+      ```ruby
+      windows_task '\\Microsoft\\Windows\\Application Experience\\ProgramDataUpdater' do
+        action :disable
+      end
+      ```
+      DOC
 
       allowed_actions :create, :delete, :run, :end, :enable, :disable, :change
       default_action :create
diff --git a/lib/chef/resource/windows_uac.rb b/lib/chef/resource/windows_uac.rb
index bb3ce35bc2..560fd387dd 100644
--- a/lib/chef/resource/windows_uac.rb
+++ b/lib/chef/resource/windows_uac.rb
@@ -22,8 +22,27 @@ class Chef
     class WindowsUac < Chef::Resource
       provides :windows_uac
 
-      description 'The windows_uac resource configures UAC on Windows hosts by setting registry keys at \'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\''
+      description 'The *windows_uac* resource configures UAC on Windows hosts by setting registry keys at `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System`'
       introduced "15.0"
+      examples <<~DOC
+      **Disable UAC prompts for the admin**:
+
+      ``` ruby
+      windows_uac 'Disable UAC prompts for the admin' do
+        enable_uac true
+        prompt_on_secure_desktop false
+        consent_behavior_admins :no_prompt
+      end
+      ```
+
+      **Disable UAC entirely**:
+
+      ``` ruby
+      windows_uac 'Disable UAC entirely' do
+        enable_uac false
+      end
+      ```
+      DOC
 
       # https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/user-account-control-group-policy-and-registry-key-settings#user-account-control-virtualize-file-and-registry-write-failures-to-per-user-locations
       property :enable_uac, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/windows_workgroup.rb b/lib/chef/resource/windows_workgroup.rb
index 8d01c8a494..b77b0fc20a 100644
--- a/lib/chef/resource/windows_workgroup.rb
+++ b/lib/chef/resource/windows_workgroup.rb
@@ -26,8 +26,24 @@ class Chef
 
       include Chef::Mixin::PowershellOut
 
-      description "Use the windows_workgroup resource to join or change the workgroup of a Windows host."
+      description "Use the **windows_workgroup** resource to join or change the workgroup of a Windows host."
       introduced "14.5"
+      examples <<~DOC
+      **Join a workgroup**:
+
+      ``` ruby
+      windows_workgroup 'myworkgroup'
+      ```
+
+      **Join a workgroup using a specific user**:
+
+      ``` ruby
+      windows_workgroup 'myworkgroup' do
+        user 'Administrator'
+        password 'passw0rd'
+      end
+      ```
+      DOC
 
       property :workgroup_name, String,
         description: "An optional property to set the workgroup name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/yum_package.rb b/lib/chef/resource/yum_package.rb
index 53d2edd5d2..b865fdad03 100644
--- a/lib/chef/resource/yum_package.rb
+++ b/lib/chef/resource/yum_package.rb
@@ -27,11 +27,92 @@ class Chef
       provides :yum_package
       provides :package, platform_family: "fedora_derived"
 
-      description "Use the yum_package resource to install, upgrade, and remove packages with Yum"\
+      description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum"\
                   " for the Red Hat and CentOS platforms. The yum_package resource is able to resolve"\
-                  " provides data for packages much like Yum can do when it is run from the command line."\
+                  " `provides` data for packages much like Yum can do when it is run from the command line."\
                   " This allows a variety of options for installing packages, like minimum versions,"\
                   " virtual provides, and library names."
+      examples <<~DOC
+        **Install an exact version**:
+
+        ``` ruby
+        yum_package 'netpbm = 10.35.58-8.el8'
+        ```
+
+        **Install a minimum version**:
+
+        ``` ruby
+        yum_package 'netpbm >= 10.35.58-8.el8'
+        ```
+
+        **Install a minimum version using the default action**:
+
+        ``` ruby
+        yum_package 'netpbm'
+        ```
+
+        **Install a version without worrying about the exact release**:
+
+        ``` ruby
+        yum_package 'netpbm-10.35*'
+        ```
+
+
+        **To install a package**:
+
+        ``` ruby
+        yum_package 'netpbm' do
+          action :install
+        end
+        ```
+
+        **To install a partial minimum version**:
+
+        ``` ruby
+        yum_package 'netpbm >= 10'
+        ```
+
+        **To install a specific architecture**:
+
+        ``` ruby
+        yum_package 'netpbm' do
+          arch 'i386'
+        end
+        ```
+
+        or:
+
+        ``` ruby
+        yum_package 'netpbm.x86_64'
+        ```
+
+        **To install a specific version-release**
+
+        ``` ruby
+        yum_package 'netpbm' do
+          version '10.35.58-8.el8'
+        end
+        ```
+
+        **Handle cookbook_file and yum_package resources in the same recipe**:
+
+        When a **cookbook_file** resource and a **yum_package** resource are
+        both called from within the same recipe, use the `flush_cache` attribute
+        to dump the in-memory Yum cache, and then use the repository immediately
+        to ensure that the correct package is installed:
+
+        ``` ruby
+        cookbook_file '/etc/yum.repos.d/custom.repo' do
+          source 'custom'
+          mode '0755'
+        end
+
+        yum_package 'pkg-that-is-only-in-custom-repo' do
+          action :install
+          flush_cache [ :before ]
+        end
+        ```
+      DOC
 
       # XXX: the coercions here are due to the provider promiscuously updating the properties on the
       # new_resource which causes immutable modification exceptions when passed an immutable node array.
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index f0d2fb8329..3552e3e558 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -25,10 +25,7 @@ class Chef
 
       provides(:yum_repository) { true }
 
-      description "Use the yum_repository resource to manage a Yum repository configuration"\
-                  " file located at /etc/yum.repos.d/repositoryid.repo on the local machine."\
-                  " This configuration file specifies which repositories to reference, how to"\
-                  " handle cached data, etc."
+      description "Use the **yum_repository** resource to manage a Yum repository configuration file located at `/etc/yum.repos.d/repositoryid.repo` on the local machine. This configuration file specifies which repositories to reference, how to handle cached data, etc."
       introduced "12.14"
 
       # http://linux.die.net/man/5/yum.conf as well as
diff --git a/lib/chef/resource/zypper_package.rb b/lib/chef/resource/zypper_package.rb
index d9083bf708..5901090abd 100644
--- a/lib/chef/resource/zypper_package.rb
+++ b/lib/chef/resource/zypper_package.rb
@@ -26,7 +26,33 @@ class Chef
       provides :zypper_package
       provides :package, platform_family: "suse"
 
-      description "Use the zypper_package resource to install, upgrade, and remove packages with Zypper for the SUSE Enterprise and OpenSUSE platforms."
+      description "Use the **zypper_package** resource to install, upgrade, and remove packages with Zypper for the SUSE Enterprise and openSUSE platforms."
+      examples <<~DOC
+        **Install a package using package manager:**
+
+        ``` ruby
+        zypper_package 'name of package' do
+          action :install
+        end
+        ```
+
+        **Install a package using local file:**
+
+        ``` ruby
+        zypper_package 'jwhois' do
+          action :install
+          source '/path/to/jwhois.rpm'
+        end
+        ```
+
+        **Install without using recommend packages as a dependency:**
+
+        ``` ruby
+        package 'apache2' do
+          options '--no-recommends'
+          end
+        ```
+      DOC
 
       property :gpg_check, [ TrueClass, FalseClass ],
         description: "Verify the package's GPG signature. Can also be controlled site-wide using the `zypper_check_gpg` config option.",
diff --git a/lib/chef/resource/zypper_repository.rb b/lib/chef/resource/zypper_repository.rb
index 502cc0194d..52240f5c49 100644
--- a/lib/chef/resource/zypper_repository.rb
+++ b/lib/chef/resource/zypper_repository.rb
@@ -26,8 +26,20 @@ class Chef
       provides(:zypper_repository) { true }
       provides(:zypper_repo) { true }
 
-      description "Use the zypper_repository resource to create Zypper package repositories on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility with the zypper_repository resource in the existing zypper cookbook."
+      description "Use the **zypper_repository** resource to create Zypper package repositories on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility with the **zypper_repository** resource in the existing **zypper** cookbook."
       introduced "13.3"
+      examples <<~DOC
+        **Add the Apache repo on openSUSE Leap 15**
+
+        ``` ruby
+        zypper_repository 'apache' do
+          baseurl 'http://download.opensuse.org/repositories/Apache'
+          path '/openSUSE_Leap_15.0'
+            type 'rpm-md'
+          priority '100'
+        end
+        ```
+      DOC
 
       property :repo_name, String,
         regex: [%r{^[^/]+$}],
diff --git a/lib/chef/scan_access_control.rb b/lib/chef/scan_access_control.rb
index 0e99832400..d81166c28a 100644
--- a/lib/chef/scan_access_control.rb
+++ b/lib/chef/scan_access_control.rb
@@ -33,7 +33,7 @@ class Chef
   # Not yet sure if this is the optimal way to solve the problem. But it's
   # progress towards the end goal.
   #
-  # TODO: figure out if all this works with OS X's negative uids
+  # TODO: figure out if all this works with macOS' negative uids
   # TODO: windows
   class ScanAccessControl
 
diff --git a/omnibus/README.md b/omnibus/README.md
index 66bdb55448..6e49f091a5 100644
--- a/omnibus/README.md
+++ b/omnibus/README.md
@@ -24,7 +24,7 @@ You create a platform-specific package using the `build project` command:
 $ bundle exec omnibus build <PROJECT>
 ```
 
-The platform/architecture type of the package created will match the platform where the `build project` command is invoked. For example, running this command on a MacBook Pro will generate a Mac OS X package. After the build completes packages will be available in the `pkg/` folder.
+The platform/architecture type of the package created will match the platform where the `build project` command is invoked. For example, running this command on a MacBook Pro will generate a macOS package. After the build completes packages will be available in the `pkg/` folder.
 
 ### Clean
 
diff --git a/spec/functional/resource/link_spec.rb b/spec/functional/resource/link_spec.rb
index 7f527cfb60..24a1f5cd7b 100644
--- a/spec/functional/resource/link_spec.rb
+++ b/spec/functional/resource/link_spec.rb
@@ -656,10 +656,10 @@ describe Chef::Resource::Link do
           end
           context "and the link does not yet exist" do
             it "links to the target file" do
-              skip("OS X/FreeBSD/AIX/Solaris symlink? and readlink working on hard links to symlinks") if os_x? || freebsd? || aix? || solaris?
+              skip("macOS/FreeBSD/AIX/Solaris symlink? and readlink working on hard links to symlinks") if os_x? || freebsd? || aix? || solaris?
               resource.run_action(:create)
               expect(File.exists?(target_file)).to be_truthy
-              # OS X gets angry about this sort of link.  Bug in OS X, IMO.
+              # macOS gets angry about this sort of link. Bug in macOS, IMO.
               expect(symlink?(target_file)).to be_truthy
               expect(readlink(target_file)).to eq(canonicalize(@other_target))
             end
@@ -675,7 +675,7 @@ describe Chef::Resource::Link do
           end
           context "and the link does not yet exist" do
             it "links to the target file" do
-              skip("OS X/FreeBSD/AIX/Solaris fails to create hardlinks to broken symlinks") if os_x? || freebsd? || aix? || solaris?
+              skip("macOS/FreeBSD/AIX/Solaris fails to create hardlinks to broken symlinks") if os_x? || freebsd? || aix? || solaris?
               resource.run_action(:create)
               expect(File.exists?(target_file) || File.symlink?(target_file)).to be_truthy
               expect(symlink?(target_file)).to be_truthy
diff --git a/spec/unit/file_access_control_spec.rb b/spec/unit/file_access_control_spec.rb
index f1f9cc9ec7..18983e6ff5 100644
--- a/spec/unit/file_access_control_spec.rb
+++ b/spec/unit/file_access_control_spec.rb
@@ -93,7 +93,7 @@ describe Chef::FileAccessControl do
     end
 
     it "wraps uids to their negative complements to correctly handle negative uids" do
-      # More: Mac OS X (at least) has negative UIDs for 'nobody' and some other
+      # More: macOS (at least) has negative UIDs for 'nobody' and some other
       # users. Ruby doesn't believe in negative UIDs so you get the diminished radix
       # complement (i.e., it wraps around the maximum size of C unsigned int) of these
       # uids. So we have to get ruby and negative uids to smoke the peace pipe
diff --git a/tasks/docs.rb b/tasks/docs.rb
index d5fd653591..ea9afc051e 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -161,15 +161,10 @@ namespace :docs_site do
     def action_list(actions)
       list = {}
       actions.sort.each do |action|
-        # skip it so we can make it the last value later
-        next if action == "nothing"
-
-        list[action.to_sym] = { "markdown" => nil }
+        # nothing is a special case that sources the content from the docs site
+        list[action.to_sym] = (action == "nothing" ? { "shortcode" => "resources_common_actions_nothing.md" } : { "markdown" => nil })
       end
 
-      # add the special case for nothing
-      list[:nothing] = { "shortcode" => "resources_common_actions_nothing.md" }
-
       list
     end
 
@@ -301,7 +296,7 @@ namespace :docs_site do
       r["syntax_full_properties_list"] = friendly_full_property_list(name, properties)
       r["actions_list"] = action_list(data["actions"])
       r["properties_list"] = properties_list(properties)
-      r["examples_list"] = nil
+      r["examples"] = data["examples"]
 
       r
     end