docs: support browser console based exploration (#3168)

Author: ST-DDT

docs/.vitepress/config.ts

@@ -3,8 +3,9 @@ import type { DefaultTheme } from 'vitepress/theme';
 import { apiPages } from './api-pages';
 import {
   algoliaIndex,
-  currentVersion,
+  version,
   versionBannerInfix,
+  versionLabel,
   versionLinks,
 } from './versions';
 
@@ -149,6 +150,26 @@ const config: UserConfig<DefaultTheme.Config> = {
         href: 'https://fosstodon.org/@faker_js',
       },
     ],
+    [
+      'script',
+      {
+        id: 'browser-console-faker',
+      },
+      `
+const logStyle = 'background: rgba(16, 183, 127, 0.14); color: rgba(255, 255, 245, 0.86); padding: 0.5rem; display: inline-block;';
+console.log(\`%cIf you would like to test Faker in the browser console, you can do so using 'await enableFaker()'.
+If you would like to test Faker in a playground, visit https://new.fakerjs.dev.\`, logStyle);
+async function enableFaker() {
+  const imported = await import('https://cdn.jsdelivr.net/npm/@faker-js/faker@${version}/+esm');
+  Object.assign(globalThis, imported);
+  console.log(\`%cYou can now start using Faker v${version}:
+e.g. 'faker.food.description()' or 'fakerZH_CN.person.firstName()'
+For other languages please refer to https://fakerjs.dev/guide/localization.html#available-locales
+For a full list of all methods please refer to https://fakerjs.dev/api/\`, logStyle);
+  return imported;
+}
+`,
+    ],
   ],
 
   themeConfig: {
@@ -197,7 +218,10 @@ const config: UserConfig<DefaultTheme.Config> = {
       },
       {
         text: 'Try it',
-        items: [{ text: 'StackBlitz ', link: 'https://fakerjs.dev/new' }],
+        items: [
+          { text: 'StackBlitz ', link: 'https://fakerjs.dev/new' },
+          { text: 'Browser Console ', link: '/guide/usage.html#browser' },
+        ],
       },
       {
         text: 'About',
@@ -222,7 +246,7 @@ const config: UserConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: currentVersion,
+        text: versionLabel,
         items: [
           {
             text: 'Release Notes',

docs/.vitepress/versions.ts

@@ -1,6 +1,6 @@
 import { execSync } from 'node:child_process';
 import * as semver from 'semver';
-import { version } from '../../package.json';
+import { version as version_ } from '../../package.json';
 
 function readBranchName(): string {
   return (
@@ -39,6 +39,11 @@ const {
 const otherVersions = readOtherLatestReleaseTagNames();
 const isReleaseBranch = /^v\d+$/.test(branchName);
 
+/**
+ * The text of the version banner describing the current version.
+ *
+ * This is `null` in production and thus should not be displayed.
+ */
 export const versionBannerInfix: string | null = (() => {
   if (deployContext === 'production') {
     return null;
@@ -55,7 +60,19 @@ export const versionBannerInfix: string | null = (() => {
   return '"a development version"';
 })();
 
-export const currentVersion = isReleaseBranch ? `v${version}` : branchName;
+/**
+ * The current version of Faker from package.json.
+ */
+export const version = version_;
+
+/**
+ * The version label to display in the top-right corner of the site.
+ */
+export const versionLabel = isReleaseBranch ? `v${version}` : branchName;
+
+/**
+ * The links to other versions of the documentation.
+ */
 export const versionLinks = [
   {
     version: 'next',
@@ -69,6 +86,9 @@ export const versionLinks = [
   // Don't link to the current branch's version.
   .filter(({ link }) => link !== `https://${branchName}.fakerjs.dev/`);
 
+/**
+ * The name of the Algolia index to use for search.
+ */
 export const algoliaIndex = isReleaseBranch
   ? `fakerjs-v${semver.major(version)}`
   : 'fakerjs-next';

docs/guide/usage.md

@@ -32,6 +32,11 @@ For more information on selecting and customizing a locale, please refer to our
 
 If you want to try it yourself, you can open your browser console via `Ctrl + Shift + J` / `F12`.
 
+On our website, you can load faker into the browser console
+
+- by using `await enableFaker()`
+- or using the following code:
+
 ```js
 const { faker } = await import('https://esm.sh/@faker-js/faker');