Migrate example to docs

Author: axelrindle

docs/examples/01-basic/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Basic",
+    "position": 1,
+    "link": {
+        "type": "generated-index",
+        "title": "Basic Examples"
+    }
+}

examples/promise.js docs/examples/01-basic/async.mdexamples/promise.js renamed to docs/examples/01-basic/async.md

@@ -1,18 +1,25 @@
-const versionCheck = require('../lib/main')
+# Async / Await
+
+The future is now! Futuristic approach leveraging top-level await.
+
+```js
+const versionCheck = require('github-version-checker')
 const options = {
-    token: require('./token'),
+    // token: '...',
     repo: 'github-version-checker',
     owner: 'axelrindle',
     currentVersion: require('../package.json').version
 }
 
-versionCheck(options).then(function (update) {
+try {
+    const update = await versionCheck(options)
     if (update) { // update is null if there is no update available, so check here
         console.log('An update is available! ' + update.name)
         console.log('You are on version ' + options.currentVersion + '!')
     } else {
         console.log('You are up to date.')
     }
-}).catch(function (error) {
-    console.error(error)
-})
+} catch (e) {
+    console.error(e)
+}
+```

examples/callback.js docs/examples/01-basic/callback.mdexamples/callback.js renamed to docs/examples/01-basic/callback.md

@@ -1,6 +1,11 @@
-const versionCheck = require('../lib/main')
+# Callback
+
+Using a plain old callback.
+
+````js
+const versionCheck = require('github-version-checker')
 const options = {
-    token: require('./token'),
+    // token: '...',
     repo: 'github-version-checker',
     owner: 'axelrindle',
     currentVersion: require('../package.json').version
@@ -19,3 +24,4 @@ versionCheck(options, function (error, update) {
         console.log('You are up to date.')
     }
 })
+```

examples/rest.js docs/examples/01-basic/promise.mdexamples/rest.js renamed to docs/examples/01-basic/promise.md

@@ -1,5 +1,11 @@
-const versionCheck = require('../lib/main')
+# Promise
+
+Modern version using a Promise-based approach.
+
+```js
+const versionCheck = require('github-version-checker')
 const options = {
+    // token: '...',
     repo: 'github-version-checker',
     owner: 'axelrindle',
     currentVersion: require('../package.json').version
@@ -17,3 +23,4 @@ versionCheck(options)
     .catch(function (error) {
         console.error(error)
     })
+```

docs/examples/02-advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Advanced",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "title": "Advanced Examples"
+    }
+}

examples/tags.js docs/examples/02-advanced/git-tags.mdexamples/tags.js renamed to docs/examples/02-advanced/git-tags.md

@@ -1,6 +1,14 @@
-const versionCheck = require('../lib/main')
+# Fetch Git tags instead of GitHub releases
+
+In case your repository does not use GitHub releases but just Git tags a call to the
+releases api won't work.
+
+Fetch the tags instead by setting `fetchTags` to `true`:
+
+```js
+const versionCheck = require('github-version-checker')
 const options = {
-    token: require('./token'),
+    token: 'my-token',
     repo: 'github-version-checker',
     owner: 'axelrindle',
     currentVersion: require('../package.json').version,
@@ -20,3 +28,4 @@ versionCheck(options, function (error, update) {
         console.log('You are up to date.')
     }
 })
+```

examples/token_from_env.js docs/examples/02-advanced/rest.mdexamples/token_from_env.js renamed to docs/examples/02-advanced/rest.md

@@ -1,19 +1,28 @@
-const versionCheck = require('../lib/main')
+# Explicitly call the REST API
+
+There may be scenarios where you explicitly want to call the REST API.
+
+Set the `token` to `false` to accomplish this:
+
+```js
+const versionCheck = require('github-version-checker')
 const options = {
+    token: false,
     repo: 'github-version-checker',
     owner: 'axelrindle',
     currentVersion: require('../package.json').version
 }
 
 versionCheck(options)
-    .then(update => {
+    .then(function (update) {
         if (update) { // update is null if there is no update available, so check here
             console.log('An update is available! ' + update.name)
             console.log('You are on version ' + options.currentVersion + '!')
         } else {
             console.log('You are up to date.')
         }
     })
-    .catch(error => {
+    .catch(function (error) {
         console.error(error)
     })
+```

docs/examples/index.md

@@ -1 +1,9 @@
+---
+sidebar_position: 0
+---
+
 # Examples
+
+Don't care about the API documentation? Look at the examples and copy paste the snippets right into your code!
+
+![undraw our solution](/illustration/undraw_our_solution_re_8yk6.svg)