feat: Add d.js docs link component (discordjs#396)

* refactor: Move branches code into a mixin * feat: Add DocsLink component * docs: Add contributing section explaining docs-link component

Author: Danktuary

CONTRIBUTING.md

@@ -253,7 +253,7 @@ to fetch all messages in a channel
 
 If you're on the `11.x` branch, you'd see "You can use `message.channel.fetchMessages()` to fetch all messages in a channel. Use the `inline` attribute to make content display inline with the content around it. Otherwise, it'll be displayed on its own line.
 
-You can refer to the `guide/.vuepress/branches.js` file to see which values are valid to use for the `version` attribute.
+You can refer to the `guide/.vuepress/mixins/branches.js` file to see which values are valid to use for the `version` attribute.
 
 #### Codeblocks and other markdown
 
@@ -277,3 +277,31 @@ message.channel.messages.fetch();
 
 </branch>
 ```
+
+### Discord.js documentation links
+
+On pages where links to the discord.js documentation are used, you can use the `<docs-link>` component. Since the discord.js documentation is split into different categories and branches, the component allows you to supply the necessary info accordingly. The only required prop is `path`.
+
+```md
+Main docs, branch version inherited from branch selector, `class/Client`:
+<docs-link path="class/Client">Link text</docs-link>
+<!-- Becomes: https://discord.js.org/#/docs/main/v11/class/Client -->
+
+Main docs, stable branch (becomes "v12" due to the aliases set in `.vuepress/mixins/branches.js`), `class/Client`:
+<docs-link branch="stable" path="class/Client">Link text</docs-link>
+<!-- Becomes: https://discord.js.org/#/docs/main/v12/class/Client -->
+
+Main docs, reply-prefix branch, `class/Client`:
+<docs-link section="main" branch="reply-prefix" path="class/Client">Link text</docs-link>
+<!-- Becomes: https://discord.js.org/#/docs/main/reply-prefix/class/Client -->
+
+Commando docs, djs-v11 branch, `class/Command`:
+<docs-link section="commando" branch="djs-v11" path="class/Command">Link text</docs-link>
+<!-- Becomes: https://discord.js.org/#/docs/commando/djs-v11/class/Command -->
+
+Collection docs, master branch (no `branch` prop set), `class/Collection?scrollTo=partition`:
+<docs-link section="collection" path="class/Collection?scrollTo=partition">Link text</docs-link>
+<!-- Becomes: https://discord.js.org/#/docs/collection/master/class/Collection?scrollTo=partition -->
+```
+
+If the `section` prop is set to `main` (or omitted) and the `branch` prop is omitted, the `branch` prop will default to the version the user has set via the site's branch selector dropdown and update accordingly. If `section` is set to anything else and `branch` is omitted, the `branch` prop will default to `'master'`.

guide/.vuepress/branches.js

@@ -6,13 +6,12 @@
 
 <script>
 import semver from 'semver';
-import branches from '../branches.js';
 import eventBus from '../eventBus.js';
-
-const [defaultBranch] = branches;
+import branches from '../mixins/branches.js';
 
 export default {
 name: 'Branch',
+mixins: [branches],
 props: {
 version: {
 type: String,
@@ -23,27 +22,16 @@ export default {
 'default': false,
 },
 },
-data() {
-return {
-selectedBranch: defaultBranch.version,
-};
-},
 computed: {
 displayContent() {
 return semver.satisfies(semver.coerce(this.version), this.selectedBranch);
 },
 },
 mounted() {
-this.selectedBranch = localStorage.getItem('branch-version') || defaultBranch.version;
 eventBus.$on('branch-update', this.updateBranch);
 },
 destroyed() {
 eventBus.$off('branch-update', this.updateBranch);
 },
-methods: {
-updateBranch(branch) {
-this.selectedBranch = branch;
-},
-},
 };
 </script>

guide/.vuepress/components/Branch.vue

@@ -10,40 +10,27 @@
 </template>
 
 <script>
-import branches from '../branches.js';
 import eventBus from '../eventBus.js';
-
-const [defaultBranch] = branches;
+import branches from '../mixins/branches.js';
 
 // `route.query` with `page.html?v=1#header` renders as `{ v: '1' }`
 // `route.query` with `page.html#header?v=1` renders as `{}`, and renders `route.hash` as `'#header?v=1'`
 // the former is plausible but the latter is more common
-function extractBranchVersion(query, hash) {
+function getVersionFromRoute({ query, hash }) {
 const versionRegex = /\?(?:v|version)=(.*)/;
-const getBranch = version => branches.find(branch => branch.aliases.includes(version) || branch.version === version);
-
-if (query.v || query.version) return getBranch(query.v || query.version);
-if (hash.length && versionRegex.test(hash)) return getBranch(hash.match(versionRegex)[1]);
-return null;
+return query.v || query.version || (hash.length && versionRegex.test(hash) ? hash.match(versionRegex)[1] : null);
 }
 
 export default {
 name: 'BranchSelector',
-data() {
-return {
-branches,
-selectedBranch: defaultBranch.version,
-};
-},
+mixins: [branches],
 mounted() {
-const branch = extractBranchVersion(this.$route.query, this.$route.hash);
+const branch = this.getBranch(getVersionFromRoute({ query: this.$route.query, hash: this.$route.hash }));
 
 if (branch) {
 this.selectedBranch = branch.version;
 return this.updateBranch();
 }
-
-this.selectedBranch = localStorage.getItem('branch-version') || defaultBranch.version;
 },
 methods: {
 updateBranch() {

guide/.vuepress/components/BranchSelector.vue

@@ -0,0 +1,53 @@
+<template>
+<a :href="link" target="_blank" rel="noopener noreferrer">
+<slot></slot> <outbound-link />
+</a>
+</template>
+
+<script>
+import eventBus from '../eventBus.js';
+import branches from '../mixins/branches.js';
+
+const baseURL = 'https://discord.js.org/#/docs';
+const docsSections = ['main', 'commando', 'collection', 'rpc'];
+
+export default {
+name: 'DocsLink',
+mixins: [branches],
+props: {
+section: {
+type: String,
+'default': 'main',
+},
+branch: String,
+path: {
+type: String,
+required: true,
+},
+},
+computed: {
+link() {
+const guideSection = docsSections.find(section => section === this.section) || docsSections[0];
+
+const branch = guideSection === 'main'
+? this.getBranch(this.branch)
+? this.formatBranch(this.getBranch(this.branch).version)
+: this.branch || this.formatBranch(this.selectedBranch)
+: this.branch || 'master';
+
+return `${baseURL}/${guideSection}/${branch}/${this.path}`;
+},
+},
+mounted() {
+eventBus.$on('branch-update', this.updateBranch);
+},
+destroyed() {
+eventBus.$off('branch-update', this.updateBranch);
+},
+methods: {
+formatBranch(version) {
+return `v${version.slice(0, 2)}`;
+},
+},
+};
+</script>

guide/.vuepress/components/DocsLink.vue

@@ -0,0 +1,35 @@
+const branches = [
+{
+label: 'v12 (stable)',
+version: '12.x',
+aliases: ['12', 'stable'],
+},
+{
+label: 'v11',
+version: '11.x',
+aliases: ['11'],
+},
+];
+
+const [defaultBranch] = branches;
+
+export default {
+data() {
+return {
+branches,
+defaultBranch,
+selectedBranch: defaultBranch.version,
+};
+},
+mounted() {
+this.selectedBranch = localStorage.getItem('branch-version') || defaultBranch.version;
+},
+methods: {
+getBranch(version) {
+return this.branches.find(branch => branch.aliases.includes(version) || branch.version === version);
+},
+updateBranch(branch) {
+this.selectedBranch = branch;
+},
+},
+};