docs: make headers linkable via clicking

Fix #10156

docs/deprecations.pug

@@ -27,7 +27,7 @@ block content
     around these deprecation warnings, but you need to test whether these options
     cause any problems for your application. Please [report any issues on GitHub](https://github.com/Automattic/mongoose/issues/new).
 
-    ## Summary
+    <h2 id="summary"><a href="#summary">Summary</a></h2>
 
     To fix all deprecation warnings, follow the below steps:
 
@@ -41,7 +41,7 @@ block content
 
     Read below for more a more detailed description of each deprecation warning.
 
-    ## The `useNewUrlParser` Option
+    <h2 id="the-usenewurlparser-option"><a href="#the-usenewurlparser-option">The <code>useNewUrlParser</code> Option</a></h2>
 
     By default, `mongoose.connect()` will print out the below warning:
 
@@ -76,7 +76,7 @@ block content
     connected, the URL parser is no longer important. If you can't connect
     with `{ useNewUrlParser: true }`, please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).
 
-    ## `findAndModify()`
+    <h2 id="findandmodify"><a href="#findandmodify"><code>findAndModify()</code></a></h2>
 
     If you use [`Model.findOneAndUpdate()`](/docs/api.html#model_Model.findOneAndUpdate),
     by default you'll see one of the below deprecation warnings.
@@ -117,7 +117,7 @@ block content
     * [`Query.findOneAndRemove()`](/docs/api.html#query_Query-findOneAndRemove)
     * [`Query.findOneAndUpdate()`](/docs/api.html#query_Query-findOneAndUpdate)
 
-    ## `ensureIndex()`
+    <h2 id="ensureindex"><a href="#ensureindex"><code>ensureIndex()</code></a></h2>
 
     If you define [indexes in your Mongoose schemas](https://mongoosejs.com/docs/guide.html#indexes), you'll see the below
     deprecation warning.
@@ -145,7 +145,7 @@ block content
     this option on without any code changes. If you discover any issues,
     please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).
 
-    ## `remove()`
+    <h2 id="remove"><a href="#remove"><code>remove()</code></a></h2>
 
     The MongoDB driver's [`remove()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#remove) is deprecated in favor of `deleteOne()` and `deleteMany()`. This is to comply with
     the [MongoDB CRUD specification](https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst),
@@ -174,7 +174,7 @@ block content
     MyModel.deleteOne({ answer: 42 });
     ```
 
-    ## `useUnifiedTopology`
+    <h2 id="useunifiedtopology"><a href="#useunifiedtopology"><code>useUnifiedTopology</code></a></h2>
 
     By default, `mongoose.connect()` will print out the below warning:
 
@@ -210,7 +210,7 @@ block content
 
     If you find any unexpected behavior, please [open up an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).
 
-    ## `update()`
+    <h2 id="update"><a href="#update"><code>update()</code></a></h2>
 
     Like `remove()`, the [`update()` function](/docs/api.html#model_Model.update) is deprecated in favor
     of the more explicit [`updateOne()`](/docs/api.html#model_Model.updateOne), [`updateMany()`](/docs/api.html#model_Model.updateMany), and [`replaceOne()`](/docs/api.html#model_Model.replaceOne) functions. You should replace
@@ -238,7 +238,7 @@ block content
     MyModel.updateMany(filter, update);
     ```
 
-    ## `count()`
+    <h2 id="count"><a href="#count"><code>count()</code></a></h2>
 
     The MongoDB server has deprecated the `count()` function in favor of two
     separate functions, [`countDocuments()`](#query_Query-countDocuments) and
@@ -281,7 +281,7 @@ block content
     MyModel.find().estimatedDocumentCount().exec();
     ```
 
-    ## `GridStore`
+    <h2 id="gridstore"><a href="#gridstore"><code>GridStore</code></a></h2>
 
     If you're using [gridfs-stream](https://www.npmjs.com/package/gridfs-stream),
     you'll see the below deprecation warning:

docs/documents.pug

@@ -35,7 +35,7 @@ block content
       <li><a href="#overwriting">Overwriting</a></li>
     </ul>
 
-    ### Documents vs Models
+    <h2 id="documents-vs-models"><a href="#documents-vs-models">Documents vs Models</a></h2>
 
     [Document](api.html#Document) and [Model](api.html#Model) are distinct
     classes in Mongoose. The Model class is a subclass of the Document class.
@@ -55,7 +55,7 @@ block content
     You should not have to create an instance of the Document class without
     going through a model.
 
-    ### Retrieving
+    <h2 id="retrieving"><a href="#retrieving">Retrieving</a></h2>
 
     When you load documents from MongoDB using model functions like [`findOne()`](api.html#model_Model.findOne),
     you get a Mongoose document back.
@@ -68,7 +68,7 @@ block content
     doc instanceof mongoose.Document; // true
     ```
 
-    ### Updating Using `save()`
+    <h2 id="updating-using-save"><a href="#updating-using-save">Updating Using <code>save()</code></a></h2>
 
     Mongoose documents track changes. You can modify a document using vanilla
     JavaScript assignments and Mongoose will convert it into [MongoDB update operators](https://docs.mongodb.com/manual/reference/operator/update/).
@@ -103,7 +103,7 @@ block content
     await doc.save(); // Throws DocumentNotFoundError
     ```
 
-    ### Updating Using Queries
+    <h2 id="updating-using-queries"><a href="#updating-using-queries">Updating Using Queries</a></h2>
 
     The [`save()`](api.html#model_Model-save) function is generally the right
     way to update a document with Mongoose. With `save()`, you get full
@@ -122,7 +122,7 @@ block content
     execute `save()` middleware. If you need save middleware and full validation,
     first query for the document and then `save()` it._
 
-    ### Validating
+    <h2 id="validating"><a href="#validating">Validating</a></h2>
 
     Documents are casted and validated before they are saved. Mongoose first casts
     values to the specified type and then validates them. Internally, Mongoose
@@ -158,7 +158,7 @@ block content
 
     Read the [validation](./validation.html) guide for more details.
 
-    ### Overwriting
+    <h2 id="overwriting"><a href="#overwriting">Overwriting</a></h2>
 
     There are 2 different ways to overwrite a document (replacing all keys in the
     document). One way is to use the

docs/jest.pug

@@ -31,7 +31,7 @@ block content
     If you choose to delve into dangerous waters and test Mongoose apps with
     Jest, here's what you need to know:
 
-    ## Recommended `testEnvironment`
+    <h2 id="recommended-testenvironment"><a href="#recommended-testenvironment">Recommended <code>testEnvironment</code></a></h2>
 
     Do **not** use Jest's default [`jsdom` test environment](https://jestjs.io/docs/en/configuration.html#testenvironment-string)
     when testing Mongoose apps, _unless_ you are explicitly testing an
@@ -54,7 +54,7 @@ block content
     };
     ```
 
-    ## Timer Mocks
+    <h2 id="timer-mocks"><a href="#timer-mocks">Timer Mocks</a></h2>
 
     Absolutely do **not** use [timer mocks](https://jestjs.io/docs/en/timer-mocks.html)
     when testing Mongoose apps. Fake timers stub out global functions like
@@ -88,7 +88,7 @@ block content
     sinon.stub(time, 'setTimeout');
     ```
 
-    ## `globalSetup` and `globalTeardown`
+    <h2 id="globalsetup-and-globalteardown"><a href="#globalsetup-and-globalteardown"><code>globalSetup</code> and <code>globalTeardown</code></a></h2>
 
     Do **not** use `globalSetup` to call `mongoose.connect()` or
     `mongoose.createConnection()`. Jest runs `globalSetup` in

docs/plugins.pug

@@ -31,7 +31,7 @@ block content
       <li><a href="#official">Officially Supported Plugins</a></li>
     </ul>
 
-    ### Example
+    <h3 id="example"><a href="#example">Example</a></h3>
 
     Plugins are a tool for reusing logic in multiple schemas. Suppose you have
     several models in your database and want to add a `loadedAt` property

docs/transactions.pug

@@ -27,7 +27,7 @@ block content
     in isolation and potentially undo all the operations if one of them fails.
     This guide will get you started using transactions with Mongoose.
 
-    ## Getting Started with Transactions
+    <h2 id="getting-started-with-transactions"><a href="#getting-started-with-transactions">Getting Started with Transactions</a></h2>
 
     To create a transaction, you first need to create a session using or [`Mongoose#startSession`](/docs/api/mongoose.html#mongoose_Mongoose-startSession)
     or [`Connection#startSession()`](/docs/api/connection.html#connection_Connection-startSession).
@@ -59,7 +59,7 @@ block content
     [require:transactions.*can save document after aborted transaction]
     ```
 
-    ## With Mongoose Documents and `save()`
+    <h2 id="with-mongoose-documents-and-save"><a href="#with-mongoose-documents-and-save">With Mongoose Documents and <code>save()</code></a></h2>
 
     If you get a [Mongoose document](/docs/documents.html) from [`findOne()`](/docs/api.html#findone_findOne)
     or [`find()`](/docs/api.html#find_find) using a session, the document will
@@ -71,7 +71,7 @@ block content
     [require:transactions.*save]
     ```
 
-    ## With the Aggregation Framework
+    <h2 id="with-the-aggregation-framework"><a href="#with-the-aggregation-framework">With the Aggregation Framework</a></h2>
 
     The `Model.aggregate()` function also supports transactions. Mongoose
     aggregations have a [`session()` helper](/docs/api.html#aggregate_Aggregate-session)
@@ -82,7 +82,7 @@ block content
     [require:transactions.*aggregate]
     ```
 
-    ## Advanced Usage
+    <h2 id="advanced-usage"><a href="#advanced-usage">Advanced Usage</a></h2>
 
     Advanced users who want more fine-grained control over when they commit or abort transactions
     can use `session.startTransaction()` to start a transaction: