feat: adding documentation with vitepress

.gitignore

@@ -71,6 +71,7 @@ versions.json
 
 # Dist
 /dist
+/docs/.vitepress/dist
 
 # Faker
 TAGS

README.md

@@ -1,6 +1,6 @@
-# Faker
+# faker.js
 
-Generate massive amounts of fake data in the browser and node.js.
+Generate massive amounts of fake data in the Browser and Node.js.
 
 [![Chat on Discord](https://img.shields.io/discord/929487054990110771)](https://discord.com/invite/4qDjAmDj4P)
 
@@ -371,6 +371,25 @@ var secondRandom = faker.datatype.number();
 console.log(firstRandom === secondRandom);
 ```
 
+## Documentation
+
+faker.js is currently in the process of migrating its documentation to Vitepress (the successor of Vuepress).
+
+**Developing the docs**
+```shell
+npm run docs:dev
+```
+
+**Building and serving the docs statically**
+```shell
+npm run docs:build # Output docs to /dist
+npm run docs:serve # Serve docs from /dist
+```
+
+## Deploying Documentation
+
+The website is kindly hosted for free by the Netlify team under their Open Source plan. See the netlify.toml for configuration.
+
 ## Tests
 
 ```shell

docs/.vitepress/config.ts

@@ -0,0 +1,113 @@
+import { defineConfig } from 'vitepress'
+
+const nav = [
+  { text: 'Guide', link: '/guide/' },
+  { text: 'Playground', link: '/playground/' },
+]
+
+const sidebar = {
+  '/': [
+    {
+      text: 'Guide',
+      children: [
+        {
+          text: 'Recent Statement and FAQs',
+          link: '/guide/recent-faqs'
+        },
+        {
+          text: 'Getting Started',
+          link: '/guide/',
+        },
+      ]
+    },
+    {
+      text: 'API',
+        children: [
+          {
+            text: 'Address',
+            link: '/api/address',
+            collapsable: false, // optional, defaults to true
+          },
+          {
+            text: 'Commerce',
+            link: '/api/commerce'
+          },
+          {
+            text: 'Company',
+            link: '/api/company'
+          },
+          {
+            text: 'Database',
+            link: '/api/database'
+          },
+          {
+            text: 'Datatype',
+            link: '/api/datatype'
+          },
+          {
+            text: 'Date',
+            link: '/api/date'
+          },
+          {
+            text: 'Fake',
+            link: '/api/fake'
+          },
+          {
+            text: 'Finance',
+            link: '/api/finance'
+          },
+          {
+            text: 'Hacker',
+            link: '/api/hacker'
+          },
+          {
+            text: 'Helpers',
+            link: '/api/helpers'
+          },
+          {
+            text: 'Image',
+            link: '/api/image'
+          },
+          {
+            text: 'Internet',
+            link: '/api/internet'
+          },
+          {
+            text: 'Localization',
+            link: '/api/localization'
+          }
+        ]
+      }
+    ]
+}
+
+// grab from process.env once this is building on netlify
+const algolia = {
+  apiKey: '',
+  indexName: '',
+  searchParameters: {
+    facetFilters: ['']
+  }
+}
+
+export default defineConfig({
+  // Empty in order to use the faker.js logo instead of a text title. 
+  // If we had a square logo, we could use it here.
+  title: ' ',
+  description: 'Generate massive amounts of fake data in the browser and node.js',
+  head: [
+    ['link', { rel: 'icon', href: '/logo.svg' }],
+    ['meta', { name: 'theme-color', content: '#40af7c'}],
+  ],
+  themeConfig: {
+    repo: 'faker-js/faker',
+    logo: '/logo-text.svg',
+    docsDir: 'docs',
+    docsBranch: 'main',
+    editLinks: true,
+    editLinkText: 'Suggest changes to this page',
+    nav,
+    sidebar,
+    algolia,
+  }
+})

docs/.vitepress/theme/components/Badge.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+defineProps<{
+  text: string
+  type: 'tip' | 'danger' | 'warning' | 'info'
+  vertical: 'top' | 'middle' | 'bottom'
+}>()
+</script>
+
+<template>
+  <span class="badge"
+    :class="type"
+    :style="{ verticalAlign: vertical }">
+    {{ text }}
+  </span>
+</template>
+
+<style scoped>
+.badge.tip {
+  background-color: #40af7c;
+}
+
+.badge.danger {
+  background-color: #cb0300;
+}
+
+.badge.warning {
+  background-color: #e7c000;
+}
+
+.badge.info {
+  background-color: #476482;
+}
+
+.badge {
+  display: inline-block;
+  font-size: 14px;
+  height: 18px;
+  line-height: 18px;
+  border-radius: 3px;
+  padding: 0 6px;
+  color: var(--c-bg);
+  vertical-align: top;
+  transition: color var(--t-color),background-color var(--t-color);
+}
+</style>

docs/.vitepress/theme/components/Playground.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+
+const faker = ref()
+const ready = ref(false)
+
+import('../../../../dist/faker').then((_faker) => {
+  window.faker = _faker.default
+  faker.value = _faker.default
+  ready.value = true
+})
+
+</script>
+
+<template>
+  <h2>🚧 Playground under construction 🚧</h2>
+  <h3>window.faker</h3>
+  <pre v-if="ready">{{ Object.keys(faker) }}</pre>
+</template>

docs/.vitepress/theme/components/index.ts

@@ -0,0 +1,7 @@
+import Playground from './Playground.vue'
+import Badge from './Badge.vue'
+
+export default {
+  Playground,
+  Badge,
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,11 @@
+import GlobalComponents from './components'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  ...DefaultTheme,
+  enhanceApp({ app }) {
+    for (const [name, component] of Object.entries(GlobalComponents)) {
+      app.component(name, component)
+    }
+  }
+}