Fix some Documentation things

docs/api_split.pug

@@ -3,15 +3,6 @@ extends layout
 append style
   link(rel="stylesheet", href="/docs/css/api.css")
 
-  style.
-    .api-nav .nav-item-sub {
-      display: block !important;
-    }
-
-    .api-content {
-      margin-top: 3em;
-    }
-
 block content
   <a class="edit-docs-link" href="#{editLink}" target="_blank">
     <img src="/docs/images/pencil.svg" />
@@ -77,7 +68,7 @@ block content
         h5 Inherits:
         ul
           li <span class="method-type">&laquo;#{prop.inherits}&raquo;</span>
-      if prop.see != null 
+      if prop.see != null && prop.see.length > 0
         h5 See:
         ul
           each see in prop.see

docs/css/api.css

@@ -28,7 +28,7 @@
 }
 
 .api-nav .nav-item-sub {
-  display: none;
+  display: block;
   font-size: 0.66em;
 }
 
@@ -46,6 +46,10 @@
   position: relative;
 }
 
+.api-content {
+  margin-top: 3em;
+}
+
 @media (max-width: 1785px) {
   .api-nav {
     display: none;

docs/css/style.css

@@ -75,7 +75,6 @@ h2 {
   margin: 30px 0;
 }
 h2 a {
-  font-size: 11px;
   position: relative;
   bottom: 4px;
 }

docs/documents.md

@@ -7,7 +7,7 @@ to documents as stored in MongoDB. Each document is an instance of its
 <ul class="toc">
   <li><a href="#documents-vs-models">Documents vs Models</a></li>
   <li><a href="#retrieving">Retrieving</a></li>
-  <li><a href="#updating-using-save">Updating Using `save()`</a></li>
+  <li><a href="#updating-using-save">Updating Using <code>save()<code></a></li>
   <li><a href="#updating-using-queries">Updating Using Queries</a></li>
   <li><a href="#validating">Validating</a></li>
   <li><a href="#overwriting">Overwriting</a></li>

docs/enterprise.md

@@ -25,38 +25,38 @@ Your subscription includes:
 
 - Security updates
 
-Tidelift’s security response team coordinates patches for new breaking security
-vulnerabilities and alerts immediately through a private channel, so your
-software supply chain is always secure.
+  Tidelift’s security response team coordinates patches for new breaking security
+  vulnerabilities and alerts immediately through a private channel, so your
+  software supply chain is always secure.
 
 - Licensing verification and indemnification
 
-Tidelift verifies license information to enable easy policy enforcement and
-adds intellectual property indemnification to cover creators and users in case
-something goes wrong. You always have a 100% up-to-date bill of materials for
-your dependencies to share with your legal team, customers, or partners.
+  Tidelift verifies license information to enable easy policy enforcement and
+  adds intellectual property indemnification to cover creators and users in case
+  something goes wrong. You always have a 100% up-to-date bill of materials for
+  your dependencies to share with your legal team, customers, or partners.
 
 - Maintenance and code improvement
 
-Tidelift ensures the software you rely on keeps working as long as you need it
-to work. Your managed dependencies are actively maintained and we recruit
-additional maintainers where required.
+  Tidelift ensures the software you rely on keeps working as long as you need it
+  to work. Your managed dependencies are actively maintained and we recruit
+  additional maintainers where required.
 
 - Package selection and version guidance
 
-We help you choose the best open source packages from the start—and then
-guide you through updates to stay on the best releases as new issues arise.
+  We help you choose the best open source packages from the start—and then
+  guide you through updates to stay on the best releases as new issues arise.
 
 - Roadmap input
 
-Take a seat at the table with the creators behind the software you use.
-Tidelift’s participating maintainers earn more income as their software is
-used by more subscribers, so they’re interested in knowing what you need.
+  Take a seat at the table with the creators behind the software you use.
+  Tidelift’s participating maintainers earn more income as their software is
+  used by more subscribers, so they’re interested in knowing what you need.
 
 - Tooling and cloud integration
 
-Tidelift works with GitHub, GitLab, BitBucket, and more. We support every
-cloud platform (and other deployment targets, too).
+  Tidelift works with GitHub, GitLab, BitBucket, and more. We support every
+  cloud platform (and other deployment targets, too).
 
 The end result? All of the capabilities you expect from commercial-grade
 software, for the full breadth of open source you use. That means less time
@@ -68,4 +68,4 @@ applications—and your business.
 </a>
 <a href="https://tidelift.com/subscription/request-a-demo?utm_source=npm-mongoose&utm_medium=referral&utm_campaign=enterprise">
   <button style="border-radius: 3px;padding: 3px;padding-left: 30px;padding-right: 30px;border: 1px solid transparent;color: white;background-color: #800;">Request a Demo</button>
-</a>
+</a>

docs/layout.pug

@@ -154,7 +154,6 @@ html(lang='en')
         .container
           #content
             block content
-        include includes/track
 
         - if (!outputUrl.startsWith('/docs/jobs'))
           div#jobs

docs/migrating_to_6.md

@@ -1,5 +1,11 @@
 ## Migrating from 5.x to 6.x
 
+<style>
+  ul > li {
+    padding: 4px 0px;
+  }
+</style>
+
 There are several [backwards-breaking changes](https://github.com/Automattic/mongoose/blob/master/CHANGELOG.md)
 you should be aware of when migrating from Mongoose 5.x to Mongoose 6.x.
 
@@ -90,7 +96,7 @@ await mongoose.connect('mongodb://localhost:27017/test', {
 });
 ```
 
-<h3 id="the-aspromise-method-for-connections"><a href="#the-aspromise-method-for-connections">The `asPromise()` Method for Connections</a></h3>
+<h3 id="the-aspromise-method-for-connections"><a href="#the-aspromise-method-for-connections">The <code>asPromise()</code> Method for Connections</a></h3>
 
 Mongoose connections are no longer [thenable](https://masteringjs.io/tutorials/fundamentals/thenable). This means that `await mongoose.createConnection(uri)` **no longer waits for Mongoose to connect**. Use `mongoose.createConnection(uri).asPromise()` instead. See [#8810](https://github.com/Automattic/mongoose/issues/8810).
 
@@ -102,7 +108,7 @@ await mongoose.createConnection(uri);
 await mongoose.createConnection(uri).asPromise();
 ```
 
-<h3 id="mongoose-connect-returns-a-promise"><a href="#mongoose-connect-returns-a-promise">`mongoose.connect()` Returns a Promise</a></h3>
+<h3 id="mongoose-connect-returns-a-promise"><a href="#mongoose-connect-returns-a-promise"><code>mongoose.connect()</code> Returns a Promise</a></h3>
 
 The `mongoose.connect()` function now always returns a promise, **not** a Mongoose instance.
 
@@ -130,7 +136,7 @@ if (existingUser) {
 }
 ```
 
-<h3 id="strictquery-is-removed-and-replaced-by-strict"><a href="#strictquery-is-removed-and-replaced-by-strict">`strictQuery` is now equal to `strict` by default</a></h3>
+<h3 id="strictquery-is-removed-and-replaced-by-strict"><a href="#strictquery-is-removed-and-replaced-by-strict"><code>strictQuery</code> is now equal to <code>strict</code> by default</a></h3>
 
 ~Mongoose no longer supports a `strictQuery` option. You must now use `strict`.~
 As of Mongoose 6.0.10, we brought back the `strictQuery` option.
@@ -222,7 +228,7 @@ const doc = new Test({
 assert.deepEqual(Object.keys(doc.toObject().profile.name), ['first', 'last']);
 ```
 
-<h3 id="sanitizefilter-and-trusted"><a href="#sanitizefilter-and-trusted">`sanitizeFilter` and `trusted()`</a></h3>
+<h3 id="sanitizefilter-and-trusted"><a href="#sanitizefilter-and-trusted"><code>sanitizeFilter</code> and <code>trusted()</code></a></h3>
 
 Mongoose 6 introduces a new `sanitizeFilter` option to globals and queries that defends against [query selector injection attacks](https://thecodebarbarian.com/2014/09/04/defending-against-query-selector-injection-attacks.html). If you enable `sanitizeFilter`, Mongoose will wrap any object in the query filter in a `$eq`:
 
@@ -239,7 +245,7 @@ To explicitly allow a query selector, use `mongoose.trusted()`:
 await Test.find({ username: 'val', pwd: mongoose.trusted({ $ne: null }) }).setOptions({ sanitizeFilter: true });
 ```
 
-<h3 id="removed-omitundefined"><a href="#removed-omitundefined">Removed `omitUndefined`: Mongoose now removes `undefined` keys in updates instead of setting them to `null`</a></h3>
+<h3 id="removed-omitundefined"><a href="#removed-omitundefined">Removed <code>omitUndefined</code>: Mongoose now removes <code>undefined</code> keys in updates instead of setting them to <code>null</code></a></h3>
 
 In Mongoose 5.x, setting a key to `undefined` in an update operation was equivalent to setting it to `null`.
 
@@ -297,7 +303,7 @@ post.tags[0] = 'javascript';
 await post.save(); // Works, no need for `markModified()`!
 ```
 
-<h3 id="typepojotomixed"><a href="#typepojotomixed">`typePojoToMixed`</a></h3>
+<h3 id="typepojotomixed"><a href="#typepojotomixed"><code>typePojoToMixed</code></a></h3>
 
 Schema paths declared with `type: { name: String }` become single nested subdocs in Mongoose 6, as opposed to Mixed in Mongoose 5. This removes the need for the `typePojoToMixed` option. See [gh-7181](https://github.com/Automattic/mongoose/issues/7181).
 
@@ -309,11 +315,11 @@ const schema = new Schema({
 });
 ```
 
-<h3 id="strictpopulate"><a href="#strictpopulate">`strictPopulate()`</a></h3>
+<h3 id="strictpopulate"><a href="#strictpopulate"><code>strictPopulate()</code></a></h3>
 
 Mongoose now throws an error if you `populate()` a path that isn't defined in your schema. This is only for cases when we can infer the local schema, like when you use `Query#populate()`, **not** when you call `Model.populate()` on a POJO. See [gh-5124](https://github.com/Automattic/mongoose/issues/5124).
 
-<h3 id="subdocument-ref-function-context"><a href="#subdocument-ref-function-context">Subdocument `ref` Function Context</a></h3>
+<h3 id="subdocument-ref-function-context"><a href="#subdocument-ref-function-context">Subdocument <code>ref</code> Function Context</a></h3>
 
 When populating a subdocument with a function `ref` or `refPath`, `this` is now the subdocument being populated, not the top-level document. See [#8469](https://github.com/Automattic/mongoose/issues/8469).
 
@@ -345,11 +351,11 @@ Single nested subdocs have been renamed to "subdocument paths". So `SchemaSingle
 
 `Aggregate#cursor()` now returns an AggregationCursor instance to be consistent with `Query#cursor()`. You no longer need to do `Model.aggregate(pipeline).cursor().exec()` to get an aggregation cursor, just `Model.aggregate(pipeline).cursor()`.
 
-<h3 id="autocreate-defaults-to-true"><a href="#autocreate-defaults-to-true">`autoCreate` Defaults to `true`</a></h3>
+<h3 id="autocreate-defaults-to-true"><a href="#autocreate-defaults-to-true"><code>autoCreate</code> Defaults to <code>true</code></a></h3>
 
 `autoCreate` is `true` by default **unless** readPreference is secondary or secondaryPreferred, which means Mongoose will attempt to create every model's underlying collection before creating indexes. If readPreference is secondary or secondaryPreferred, Mongoose will default to `false` for both `autoCreate` and `autoIndex` because both `createCollection()` and `createIndex()` will fail when connected to a secondary.
 
-<h3 id="no-more-context-query"><a href="#no-more-context-query">No More `context: 'query'`</a></h3>
+<h3 id="no-more-context-query"><a href="#no-more-context-query">No More <code>context: 'query'</code></a></h3>
 
 The `context` option for queries has been removed. Now Mongoose always uses `context = 'query'`.
 
@@ -363,7 +369,7 @@ When connected to a replica set, connections now emit 'disconnected' when connec
 
 However, Mongoose 6 does **not** buffer commands while a connection is disconnected. So you can still successfully execute commands like queries with `readPreference = 'secondary'`, even if the Mongoose connection is in the disconnected state.
 
-<h3 id="removed-execpopulate"><a href="#removed-execpopulate">Removed `execPopulate()`</a></h3>
+<h3 id="removed-execpopulate"><a href="#removed-execpopulate">Removed <code>execPopulate()</code></a></h3>
 
 `Document#populate()` now returns a promise and is now no longer chainable.
 
@@ -373,15 +379,15 @@ However, Mongoose 6 does **not** buffer commands while a connection is disconnec
   await doc.populate([{path: 'path1', select: 'select1'}, {path: 'path2', select: 'select2'}]);
   ```
 
-<h3 id="create-with-empty-array"><a href="#create-with-empty-array">`create()` with Empty Array</a></h3>
+<h3 id="create-with-empty-array"><a href="#create-with-empty-array"><code>create()</code> with Empty Array</a></h3>
 
 `await Model.create([])` in v6.0 returns an empty array when provided an empty array, in v5.0 it used to return `undefined`. If any of your code is checking whether the output is `undefined` or not, you need to modify it with the assumption that `await Model.create(...)` will always return an array if provided an array.
 
 <h3 id="removed-nested-path-merging"><a href="#removed-nested-path-merging">Removed Nested Path Merging</a></h3>
 
 `doc.set({ child: { age: 21 } })` now works the same whether `child` is a nested path or a subdocument: Mongoose will overwrite the value of `child`. In Mongoose 5, this operation would merge `child` if `child` was a nested path.
 
-<h3 id="objectid-valueof"><a href="#objectid-valueof">ObjectId `valueOf()`</a></h3>
+<h3 id="objectid-valueof"><a href="#objectid-valueof">ObjectId <code>valueOf()</code></a></h3>
 
 Mongoose now adds a `valueOf()` function to ObjectIds. This means you can now use `==` to compare an ObjectId against a string.
 
@@ -391,19 +397,19 @@ const a = ObjectId('6143b55ac9a762738b15d4f0');
 a == '6143b55ac9a762738b15d4f0'; // true
 ```
 
-<h3 id="immutable-createdat"><a href="#immutable-createdat">Immutable `createdAt`</a></h3>
+<h3 id="immutable-createdat"><a href="#immutable-createdat">Immutable <code>createdAt</code></a></h3>
 
 If you set `timestamps: true`, Mongoose will now make the `createdAt` property `immutable`. See [gh-10139](https://github.com/Automattic/mongoose/issues/10139)
 
-<h3 id="removed-validator-isasync"><a href="#removed-validator-isasync">Removed Validator `isAsync`</a></h3>
+<h3 id="removed-validator-isasync"><a href="#removed-validator-isasync">Removed Validator <code>isAsync</code></a></h3>
 
 `isAsync` is no longer an option for `validate`. Use an `async function` instead.
 
-<h3 id="removed-safe"><a href="#removed-safe">Removed `safe`</a></h3>
+<h3 id="removed-safe"><a href="#removed-safe">Removed <code>safe</code></a></h3>
 
 `safe` is no longer an option for schemas, queries, or `save()`. Use `writeConcern` instead.
 
-<h3 id="schematype-set-parameters"><a href="#schematype-set-parameters">SchemaType `set` parameters</a></h3>
+<h3 id="schematype-set-parameters"><a href="#schematype-set-parameters">SchemaType <code>set</code> parameters</a></h3>
 
 Mongoose now calls setter functions with `priorValue` as the 2nd parameter, rather than `schemaType` in Mongoose 5.
 
@@ -431,7 +437,7 @@ const user = new User({ name: 'Robert Martin' });
 console.log(user.name); // 'robert martin'
 ```
 
-<h3 id="toobject-and-tojson-use-nested-schema-minimize"><a href="#toobject-and-tojson-use-nested-schema-minimize">`toObject()` and `toJSON()` Use Nested Schema `minimize`</a></h3>
+<h3 id="toobject-and-tojson-use-nested-schema-minimize"><a href="#toobject-and-tojson-use-nested-schema-minimize"><code>toObject()</code> and <code>toJSON()</code> Use Nested Schema <code>minimize</code></a></h3>
 
 This change was technically released with 5.10.5, but [caused issues for users migrating from 5.9.x to 6.x](https://github.com/Automattic/mongoose/issues/10827).
 In Mongoose `< 5.10.5`, `toObject()` and `toJSON()` would use the top-level schema's `minimize` option by default.

docs/schematypes.md

@@ -9,21 +9,14 @@ SchemaTypes handle definition of path
 [queries](./api.html#query-js),
 and other general characteristics for Mongoose document properties.
 
-<ul class="toc">
-  <li><a href="#what-is-a-schema-type">What is a SchemaType?</a></li>
-  <li><a href="#schematype-options">SchemaType Options</a></li>
-  <li><a href="#customtypes">Creating Custom Types</a></li>
-  <li><a href="#path">The `schema.path()` Function</a></li>
-  <li><a href="#further-reading">Further Reading</a></li>
-</ul>
-
 * [What is a SchemaType?](#what-is-a-schematype)
 * [The `type` Key](#type-key)
 * [SchemaType Options](#schematype-options)
 * [Usage Notes](#usage-notes)
 * [Getters](#getters)
 * [Custom Types](#customtypes)
 * [The `schema.path()` Function](#path)
+* [Further Reading](#further-reading)
 
 <h3 id="what-is-a-schematype"><a href="#what-is-a-schematype">What is a SchemaType?</a></h3>
 
@@ -117,7 +110,7 @@ m.map = new Map([['key', 'value']]);
 m.save(callback);
 ```
 
-<h3 id="type-key"><a href="#type-key">The `type` Key</a></h3>
+<h3 id="type-key"><a href="#type-key">The <code>type</code> Key</a></h3>
 
 `type` is a special property in Mongoose schemas. When Mongoose finds
 a nested property named `type` in your schema, Mongoose assumes that

docs/source/api.js

@@ -159,16 +159,20 @@ function parse() {
             // The remainder is simply taken by a call to "slice" (also the text is trimmed later)
             const textMatches = /^(.*? (?=#|\/|(?:https?:)|$))/i.exec(tag.string);
 
-            let text;
+            let text = undefined;
+            let url = undefined;
             if (textMatches === null || textMatches === undefined) {
               // warn because this most likely is a badly defined "@see"
               console.warn(`No Text Matches found in @see for "${ctx.constructor}.${ctx.name}"`)
-              break;
+
+              // if no text is found, add text as url and use the url itself as the text
+              url = tag.string;
+              text = tag.string;
             } else {
               text = textMatches[1].trim();
+              url = tag.string.slice(text.length).trim();
             }
 
-            const url = tag.string.slice(text.length).trim();
             ctx.see.push({
               text: text || 'No Description', // fallback text, so that the final text does not end up as a empty element that cannot be seen
               url: url || undefined, // change to be "undefined" if text is empty or non-valid

index.pug

@@ -189,12 +189,10 @@ html(lang='en')
               a(rel='sponsored', href=sponsor.website || sponsor.profile)
                 img.sponsor(src=sponsor.image || 'https://next-images.opencollective.com/_next/image?url=%2Fstatic%2Fimages%2Fopencollective-icon.png&w=96&q=75', style='height:50px', alt=sponsor.alt)
 
-        <div class="sponsor">
-          Sponsor <a href="https://opencollective.com/mongoose">Mongoose on OpenCollective</a>
-          to get your company's logo above!
-        </div>
+        div.sponsors
+          :markdown
+            Sponsor [Mongoose on OpenCollective](https://opencollective.com/mongoose) to get your company's logo above!
 
     p#footer Licensed under MIT.
     script.
       document.body.className = 'load';
-    include docs/includes/track

lib/connection.js

@@ -1117,7 +1117,7 @@ Connection.prototype.collection = function(name, options) {
  * @param {Function} fn plugin callback
  * @param {Object} [opts] optional options
  * @return {Connection} this
- * @see plugins ./plugins.html
+ * @see plugins /docs/plugins
  * @api public
  */
 

lib/document.js

@@ -4246,7 +4246,7 @@ Document.prototype.equals = function(doc) {
  * @param {Function} [options.transform=null] Function that Mongoose will call on every populated document that allows you to transform the populated document.
  * @param {Object} [options.options=null] Additional options like `limit` and `lean`.
  * @param {Function} [callback] Callback
- * @see population ./populate.html
+ * @see population /docs/populate
  * @see Query#select #query_Query-select
  * @see Model.populate #model_Model-populate
  * @memberOf Document

lib/index.js

@@ -688,7 +688,7 @@ Mongoose.prototype._applyPlugins = function(schema, options) {
  * @param {Function} fn plugin callback
  * @param {Object} [opts] optional options
  * @return {Mongoose} this
- * @see plugins ./plugins.html
+ * @see plugins /docs/plugins
  * @api public
  */