mongodb · norareidy · Jan 31, 2025 · Jan 27, 2025 · Jan 27, 2025 · Jan 28, 2025
diff --git a/.gitignore b/.gitignore
@@ -15,5 +15,7 @@ meta.yaml
 source/includes/hash.rst
 source/includes/table/
 source/includes/toc
+bson-ruby/
+mongo-ruby-driver/
 fabfile
 giza.log
diff --git a/config/redirects b/config/redirects
diff --git a/snooty.toml b/snooty.toml
@@ -2,7 +2,6 @@ name = "ruby-driver"
 title = "Ruby MongoDB Driver"
 toc_landing_pages = [
     "/get-started",
-    "/connect",
     "/write",
     "/indexes",
     "/databases-collection",
@@ -24,4 +23,4 @@ version-number = "2.21"
 patch-version-number = "{+version-number+}.0"                     # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
 version = "v{+version-number+}"
 stable-api = "Stable API"
-api-root = "https://www.mongodb.com/docs/ruby-driver/current/api"
+api-root = "https://www.mongodb.com/docs/ruby-driver/current/api/"
diff --git a/source/aggregation.txt b/source/aggregation.txt
@@ -199,9 +199,8 @@ This example creates pipeline stages to perform the following actions:
 
     To run the following example, you must create an Atlas Search index on the ``restaurants``
     collection that covers the ``name`` field. Then, replace the ``"<your_search_index_name>"``
-    placeholder with the name of the index. 
-
-.. TODO: Add a link in the callout to the Atlas Search index creation guide.
+    placeholder with the name of the index. To learn how to create an Atlas Search index,
+    see the :ref:`ruby-atlas-search-index` guide.
 
 .. io-code-block::
     :copyable:
@@ -255,4 +254,4 @@ API Documentation
 ~~~~~~~~~~~~~~~~~
 
 To learn more about the Ruby driver's aggregation methods, see the
-API documentation for `Aggregation <{+api-root+}/Mongo/Collection/View/Aggregation.html>`__.
+API documentation for :ruby-api:`Aggregation <Collection/View/Aggregation.html>`.
diff --git a/...e/old-content/tutorials/common-errors.txt → source/common-errors.txt b/...e/old-content/tutorials/common-errors.txt → source/common-errors.txt
@@ -1,6 +1,8 @@
-*************
+.. _ruby-common-errors:
+
+=============
 Common Errors
-*************
+=============
 
 .. default-domain:: mongodb
 
@@ -12,7 +14,7 @@ Common Errors
 
 
 No Server is Available Matching Preference
-==========================================
+------------------------------------------
 
 If you receive the following error:
 
@@ -39,14 +41,13 @@ this, you can try the following:
   host list.
 - If you are connecting to Atlas, ensure that the firewall rules are configured
   correctly. See the documentation on `Cluster Security <https://www.mongodb.com/docs/atlas/setup-cluster-security/>`_.
-- If your application uses a forking web server, see the documentation on :ref:`Forking <forking>`.
 
 See more on this issue here:
 `RUBY-1281 <https://jira.mongodb.org/browse/RUBY-1281>`_.
 
 
 ``OperationFailure`` When Reading ``local`` Database With Auth On
-=================================================================
+-----------------------------------------------------------------
 
 If you are getting the following error when trying to read the ``local`` database:
 
@@ -66,7 +67,7 @@ You can find more information about this issue here:
 
 
 ``SocketTimeoutError`` and name resolution errors on EC2
-========================================================
+--------------------------------------------------------
 
 Some users reported getting the following error:
 
@@ -102,7 +103,7 @@ You can find more information about this issue here:
 
 
 ``Mongo::Auth::Unauthorized`` User is Not Authorized to Access
-==============================================================
+--------------------------------------------------------------
 
 Some users reported getting the following error:
 

diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt
@@ -292,4 +292,4 @@ API Documentation
 -----------------
 
 For more information about ``Mongo::Client`` options for the {+driver-short+},
-see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .
+see the API documentation for :ruby-api:`Mongo::Client <Client.html>`.
diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt
@@ -29,9 +29,9 @@ Atlas
 To connect to a MongoDB deployment on Atlas, include the following elements
 in your connection string:
 
-- The URL of your Atlas cluster
-- Your MongoDB username
-- Your MongoDB password
+- URL of your Atlas cluster
+- MongoDB username
+- MongoDB password
 
 Then, pass your connection string to the ``Mongo::Client`` constructor.
 
@@ -128,4 +128,4 @@ API Documentation
 -----------------
 
 To learn more about creating a ``Mongo::Client`` object with the {+driver-short+},
-see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .
+see the API documentation for :ruby-api:`Mongo::Client <Client.html>` .
diff --git a/source/connect/csot.txt b/source/connect/csot.txt
@@ -237,5 +237,5 @@ API Documentation
 To learn more about using timeouts with the {+driver-short+}, see the following
 API documentation:
 
-- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__
-- `Mongo::Session <{+api-root+}/Mongo/Session.html>`__
+- :ruby-api:`Mongo::Client <Client.html>`
+- :ruby-api:`Mongo::Session <Session.html>`
diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt
@@ -56,8 +56,8 @@ A standard connection string includes the following components:
 
      - Optional. Authentication credentials. If you include these, the client
        authenticates the user against the database specified in ``authSource``.
-       For more information about the ``authSource`` connection option, see
-       :ref:`ruby-auth`. 
+       For more information about the ``authSource`` connection option, see the
+       :ref:`ruby-authentication-mechanisms` guide. 
 
    * - ``hostname[:port]``
 
@@ -132,4 +132,4 @@ API Documentation
 -----------------
 
 To learn more about creating a ``Mongo::Client`` object with the {+driver-short+},
-see the API documentation for `Mongo::Client. <{+api-root+}/Mongo/Client.html>`__
+see the API documentation for :ruby-api:`Mongo::Client. <Client.html>`
diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt
@@ -113,4 +113,4 @@ API Documentation
 For more information about using the {+stable-api+} with the {+driver-short+}, see the 
 following API documentation: 
 
-- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__
+- :ruby-api:`Mongo::Client <Client.html>`
diff --git a/source/connect/tls.txt b/source/connect/tls.txt
@@ -322,5 +322,5 @@ API Documentation
 For more information about any of the types and methods discussed in this guide,
 see the following API documentation:
 
-- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__
-- `tls_context_hooks <{+api-root+/Mongo.html#tls_context_hooks-class_method}>`__
+- :ruby-api:`Mongo::Client <Client.html>`
+- `tls_context_hooks <{+api-root+}Mongo.html#tls_context_hooks-class_method>`__
diff --git a/source/data-formats.txt b/source/data-formats.txt
@@ -23,6 +23,7 @@ Data Formats
    :maxdepth: 1
 
    Time Series Data </data-formats/time-series>
+   BSON </data-formats/bson>
 
 Overview
 --------
@@ -32,3 +33,4 @@ application. To learn how to work with these data formats, see the following
 sections:
 
 - :ref:`ruby-time-series`: Learn how to create a time series collection and interact with time series data.
+- :ref:`ruby-bson-tutorial`: Learn how to work with BSON data by using the {+driver-short+}'s BSON library.