Merge pull request #12690 from hasezoey/updateRemainingLinks

[DOCS] Update remaining relative and static links, also add style guidelines for documentation

CONTRIBUTING.md

@@ -35,6 +35,7 @@ If you have a question about Mongoose (not a bug report) please post it to eithe
 - Write typings-tests if you modify the typescript-typings. (tests are in the [test/types](https://github.com/Automattic/mongoose/tree/master/test/types) directory).
 
 ### Running the tests
+
 - Open a terminal and navigate to the root of the project
 - execute `npm install` to install the necessary dependencies
 - execute `npm run mongo` to start a MongoDB instance on port 27017. This step is optional, if you have already a database running on port 27017. To spin up a specific mongo version, you can do it by executing `npm run mongo -- {version}`. E.g. you want to spin up a mongo 4.2.2 server, you execute `npm run mongo -- 4.2.2`
@@ -50,7 +51,7 @@ If you have a question about Mongoose (not a bug report) please post it to eithe
 
 To contribute to the [API documentation](http://mongoosejs.com/docs/api.html) just make your changes to the inline documentation of the appropriate [source code](https://github.com/Automattic/mongoose/tree/master/lib) in the master branch and submit a [pull request](https://help.github.com/articles/using-pull-requests/). You might also use the github [Edit](https://github.com/blog/844-forking-with-the-edit-button) button.
 
-To contribute to the [guide](http://mongoosejs.com/docs/guide.html) or [quick start](http://mongoosejs.com/docs/index.html) docs, make your changes to the appropriate `.pug` files in the [docs](https://github.com/Automattic/mongoose/tree/master/docs) directory of the master branch and submit a pull request. Again, the [Edit](https://github.com/blog/844-forking-with-the-edit-button) button might work for you here.
+To contribute to the [guide](http://mongoosejs.com/docs/guide.html) or [quick start](http://mongoosejs.com/docs/index.html) docs, make your changes to the appropriate `.pug` / `.md` files in the [docs](https://github.com/Automattic/mongoose/tree/master/docs) directory of the master branch and submit a pull request. Again, the [Edit](https://github.com/blog/844-forking-with-the-edit-button) button might work for you here.
 
 If you'd like to preview your documentation changes, first commit your changes to your local master branch, then execute:
 
@@ -59,29 +60,30 @@ If you'd like to preview your documentation changes, first commit your changes t
 
 Visit `http://localhost:8089` and you should see the docs with your local changes. Make sure you `npm run docs:clean` before committing, because automated generated files to `docs/*` should **not** be in PRs.
 
+#### Documentation Style Guidelines
+
+There are some guidelines to keep the style for the documentation consistent:
+
+- All links that refer to some other file in the mongoose documentation needs to be relative without a prefix unless required (use `guide.html` over `./guide.html` or `/docs/guide.html`)
+
 ### Plugins website
 
 The [plugins](http://plugins.mongoosejs.io/) site is also an [open source project](https://github.com/vkarpov15/mongooseplugins) that you can get involved with. Feel free to fork and improve it as well!
 
-
 ## Financial contributions
 
 We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/mongoose).
 Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.
 
-
 ## Credits
 
-
 ### Contributors
 
 Thank you to all the people who have already contributed to mongoose!
 <a href="https://github.com/Automattic/mongoose/graphs/contributors"><img src="https://opencollective.com/mongoose/contributors.svg?width=890" /></a>
 
-
 ### Backers
 
 Thank you to all our backers! [[Become a backer](https://opencollective.com/mongoose#backer)]
 
 <a href="https://opencollective.com/mongoose#backers" target="_blank"><img src="https://opencollective.com/mongoose/backers.svg?width=890"></a>
-

docs/async-await.md

@@ -62,7 +62,7 @@ async function awaitUpdate() {
 }
 ```
 
-Note that the specific fulfillment values of different Mongoose methods vary, and may be affected by configuration. Please refer to the [API documentation](./api.html) for information about specific methods.
+Note that the specific fulfillment values of different Mongoose methods vary, and may be affected by configuration. Please refer to the [API documentation](api.html) for information about specific methods.
 
 ### Async Functions
 
@@ -108,7 +108,7 @@ Under the hood, [async/await is syntactic sugar](https://developer.mozilla.org/e
 Due to the surprisingly simple way promises are implemented in JavaScript, the keyword `await` will try to unwrap any object with a property whose key is the string ‘then’ and whose value is a function. 
 Such objects belong to a broader class of objects called [thenables](https://masteringjs.io/tutorials/fundamentals/thenable). 
 If the thenable being unwrapped is a genuine promise, e.g. an instance of the [Promise constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), we enjoy several guarantees about how the object’s ‘then’ function will behave. 
-However, Mongoose provides several static helper methods that return a different class of thenable object called a [Query](./queries.html)--and [Queries are not promises](./queries.html#queries-are-not-promises). 
+However, Mongoose provides several static helper methods that return a different class of thenable object called a [Query](queries.html)--and [Queries are not promises](queries.html#queries-are-not-promises). 
 Because Queries are also *thenables*, we can interact with a Query using async/await just as we would interact with a genuine promise, with one key difference: observing the fulfillment value of a genuine promise cannot under any circumstances change that value, but trying to re-observe the value of a Query may cause the Query to be re-executed.
 
 ```javascript
@@ -148,4 +148,4 @@ async function observeQuery() {
 
 You are most likely to accidentally re-execute queries in this way when mixing callbacks with async/await.
  This is never necessary and should be avoided.
- If you need a Query to return a fully-fledged promise instead of a thenable, you can use [Query#exec()](./api/query.html#query_Query-exec).
+ If you need a Query to return a fully-fledged promise instead of a thenable, you can use [Query#exec()](api/query.html#query_Query-exec).

docs/connections.md

@@ -60,7 +60,7 @@ setTimeout(function() {
 }, 60000);
 ```
 
-To disable buffering, turn off the [`bufferCommands` option on your schema](./guide.html#bufferCommands).
+To disable buffering, turn off the [`bufferCommands` option on your schema](guide.html#bufferCommands).
 If you have `bufferCommands` on and your connection is hanging, try turning
 `bufferCommands` off to see if you haven't opened a connection properly.
 You can also disable `bufferCommands` globally:
@@ -178,7 +178,7 @@ See [this page](http://mongodb.github.io/node-mongodb-native/3.1/reference/faq/)
 <h3 id="callback"><a href="#callback">Callback</a></h3>
 
 The `connect()` function also accepts a callback parameter and returns a
-[promise](./promises.html).
+[promise](promises.html).
 
 ```javascript
 mongoose.connect(uri, options, function(error) {
@@ -379,8 +379,8 @@ The `mongoose.createConnection()` function takes the same arguments as
 const conn = mongoose.createConnection('mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]', options);
 ```
 
-This [connection](./api.html#connection_Connection) object is then used to
-create and retrieve [models](./api.html#model_Model). Models are
+This [connection](api.html#connection_Connection) object is then used to
+create and retrieve [models](api.html#model_Model). Models are
 **always** scoped to a single connection.
 
 ```javascript

docs/documents.md

@@ -1,8 +1,8 @@
 ## Documents
 
-Mongoose [documents](./api/document.html) represent a one-to-one mapping
+Mongoose [documents](api/document.html) represent a one-to-one mapping
 to documents as stored in MongoDB. Each document is an instance of its
-[Model](./models.html).
+[Model](models.html).
 
 <ul class="toc">
   <li><a href="#documents-vs-models">Documents vs Models</a></li>
@@ -134,7 +134,7 @@ await Person.updateOne({}, { age: 'bar' });
 await Person.updateOne({}, { age: -1 }, { runValidators: true });
 ```
 
-Read the [validation](./validation.html) guide for more details.
+Read the [validation](validation.html) guide for more details.
 
 <h2 id="overwriting"><a href="#overwriting">Overwriting</a></h2>
 

docs/faq.md

@@ -119,7 +119,7 @@ console.log(new Model());
 
 **A**. This is a performance optimization. These empty objects are not saved
 to the database, nor are they in the result `toObject()`, nor do they show
-up in `JSON.stringify()` output unless you turn off the [`minimize` option](./guide.html#minimize).
+up in `JSON.stringify()` output unless you turn off the [`minimize` option](guide.html#minimize).
 
 The reason for this behavior is that Mongoose's change detection
 and getters/setters are based on [`Object.defineProperty()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty).
@@ -128,11 +128,11 @@ the overhead of running `Object.defineProperty()` every time a document is creat
 mongoose defines properties on the `Model` prototype when the model is compiled.
 Because mongoose needs to define getters and setters for `nested.prop`, `nested`
 must always be defined as an object on a mongoose document, even if `nested`
-is undefined on the underlying [POJO](./guide.html#minimize).
+is undefined on the underlying [POJO](guide.html#minimize).
 
 <hr id="arrow-functions" />
 
-<a class="anchor" href="#arrow-functions">**Q**</a>. I'm using an arrow function for a [virtual](./guide.html#virtuals), [middleware](./middleware.html), [getter](./api.html#schematype_SchemaType-get)/[setter](./api.html#schematype_SchemaType-set), or [method](./guide.html#methods) and the value of `this` is wrong.
+<a class="anchor" href="#arrow-functions">**Q**</a>. I'm using an arrow function for a [virtual](guide.html#virtuals), [middleware](middleware.html), [getter](api.html#schematype_SchemaType-get)/[setter](api.html#schematype_SchemaType-set), or [method](guide.html#methods) and the value of `this` is wrong.
 
 **A**. Arrow functions [handle the `this` keyword much differently than conventional functions](https://masteringjs.io/tutorials/fundamentals/arrow#why-not-arrow-functions).
 Mongoose getters/setters depend on `this` to give you access to the document that you're writing to, but this functionality does not work with arrow functions. Do **not** use arrow functions for mongoose getters/setters unless do not intend to access the document in the getter/setter.
@@ -225,7 +225,7 @@ new Schema({
 <a class="anchor" href="#model_functions_hanging">**Q**</a>. All function calls on my models hang, what am I doing wrong?
 
 **A**. By default, mongoose will buffer your function calls until it can
-connect to MongoDB. Read the [buffering section of the connection docs](./connections.html#buffering)
+connect to MongoDB. Read the [buffering section of the connection docs](connections.html#buffering)
 for more information.
 
 <hr id="enable_debugging" />
@@ -245,7 +245,7 @@ mongoose.set('debug', { color: false })
 mongoose.set('debug', { shell: true })
 ```
 
-For more debugging options (streams, callbacks), see the ['debug' option under `.set()`](./api.html#mongoose_Mongoose-set).
+For more debugging options (streams, callbacks), see the ['debug' option under `.set()`](api.html#mongoose_Mongoose-set).
 
 <hr id="callback_never_executes" />