From 51a88634092dbe17985e434572385af4e99d1022 Mon Sep 17 00:00:00 2001 From: Shinigami Date: Sun, 7 Aug 2022 04:54:28 +0800 Subject: docs: use vitepress v1 (#993) --- docs/.vitepress/config.ts | 204 +++++++++++++++++++++------------------ docs/about/team.md | 4 +- docs/about/team/TeamMember.ts | 7 -- docs/about/team/TeamMember.vue | 76 --------------- docs/about/team/TeamPage.vue | 89 +++++++---------- docs/about/team/members.json | 132 ++++++++++++++++++------- docs/guide/migration-guide-v5.md | 85 ++++++++++++++++ docs/index.md | 45 +++++---- docs/migration-guide-v5/index.md | 85 ---------------- 9 files changed, 359 insertions(+), 368 deletions(-) delete mode 100644 docs/about/team/TeamMember.ts delete mode 100644 docs/about/team/TeamMember.vue create mode 100644 docs/guide/migration-guide-v5.md delete mode 100644 docs/migration-guide-v5/index.md (limited to 'docs') diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 91e7fd2f..9b013d2e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,93 +1,7 @@ -import type { DefaultTheme } from 'vitepress'; import { defineConfig } from 'vitepress'; import { apiPages } from './api-pages'; import { currentVersion, oldVersions } from './versions'; -const nav: DefaultTheme.NavItem[] = [ - { text: 'Guide', link: '/guide/' }, - // { text: 'Playground', link: '/playground/' }, - { - text: 'Ecosystem', - items: [ - { text: 'Discord ', link: 'https://chat.fakerjs.dev' }, - { text: 'StackBlitz ', link: 'https://fakerjs.dev/new' }, - { text: 'Twitter ', link: 'https://twitter.com/faker_js' }, - ], - }, - { - text: 'About', - items: [ - { - text: 'Announcements', - link: '/about/announcements', - }, - { - text: 'Team', - link: '/about/team', - }, - ], - }, - { - text: currentVersion, - items: [ - { - text: 'Release Notes', - link: 'https://github.com/faker-js/faker/releases', - }, - ...oldVersions.map(({ version, link }) => ({ - text: version, - link, - })), - ], - }, -]; - -const sidebar: DefaultTheme.MultiSideBarConfig = { - '/about': [ - { - text: 'About', - children: [ - { - text: 'Announcements', - link: '/about/announcements', - children: [ - { text: '2022-01-14', link: '/about/announcements/2022-01-14' }, - ], - }, - { - text: 'Team', - link: '/about/team', - }, - ], - }, - ], - '/': [ - { - text: 'Guide', - children: [ - { - text: 'Getting Started', - link: '/guide/', - }, - ], - }, - { - text: 'API', - children: apiPages, - }, - { - text: 'Migrating from Faker v5', - link: '/migration-guide-v5/', - }, - ], -}; - -const algolia: DefaultTheme.AlgoliaSearchOptions = { - apiKey: process.env.API_KEY, - appId: process.env.APP_ID, - indexName: 'fakerjs', -}; - const description = 'Generate massive amounts of fake (but reasonable) data for testing and development.'; const image = 'https://fakerjs.dev/social-image.png'; @@ -95,6 +9,7 @@ const image = 'https://fakerjs.dev/social-image.png'; export default defineConfig({ title: 'Faker', description, + head: [ ['link', { rel: 'icon', href: '/logo.svg' }], ['meta', { name: 'theme-color', content: '#40af7c' }], @@ -141,15 +56,116 @@ export default defineConfig({ }, ], ], + themeConfig: { - repo: 'faker-js/faker', logo: '/logo.svg', - docsDir: 'docs', - docsBranch: 'main', - editLinks: true, - editLinkText: 'Suggest changes to this page', - nav, - sidebar, - algolia, + + editLink: { + pattern: 'https://github.com/faker-js/faker/edit/main/docs/:path', + text: 'Suggest changes to this page', + }, + + socialLinks: [ + { icon: 'twitter', link: 'https://twitter.com/faker_js' }, + { icon: 'discord', link: 'https://chat.fakerjs.dev' }, + { icon: 'github', link: 'https://github.com/faker-js/faker' }, + ], + + algolia: { + apiKey: process.env.API_KEY, + appId: process.env.APP_ID, + indexName: 'fakerjs', + }, + + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright ยฉ 2022-present Faker.', + }, + + nav: [ + { text: 'Guide', link: '/guide/' }, + // { text: 'Playground', link: '/playground/' }, + { + text: 'Ecosystem', + items: [{ text: 'StackBlitz ', link: 'https://fakerjs.dev/new' }], + }, + { + text: 'About', + items: [ + { + text: 'Announcements', + link: '/about/announcements', + }, + { + text: 'Team', + link: '/about/team', + }, + ], + }, + { + text: currentVersion, + items: [ + { + text: 'Release Notes', + link: 'https://github.com/faker-js/faker/releases', + }, + ...oldVersions.map(({ version, link }) => ({ + text: version, + link, + })), + ], + }, + ], + + sidebar: { + '/guide/': [ + { + text: 'Guide', + items: [ + { + text: 'Getting Started', + link: '/guide/', + }, + ], + }, + { + text: 'API', + items: apiPages, + }, + { + text: 'Migrations', + items: [ + { + text: 'Migrating from Faker v5', + link: '/guide/migration-guide-v5', + }, + ], + }, + ], + '/api/': [ + { + text: 'API', + items: apiPages, + }, + ], + '/about/': [ + { + text: 'About', + items: [ + { + text: 'Announcements', + link: '/about/announcements', + // children: [ + // { text: '2022-01-14', link: '/about/announcements/2022-01-14' }, + // ], + }, + { + text: 'Team', + link: '/about/team', + }, + ], + }, + ], + }, }, }); diff --git a/docs/about/team.md b/docs/about/team.md index 9013ee90..a3502b76 100644 --- a/docs/about/team.md +++ b/docs/about/team.md @@ -1,9 +1,11 @@ --- +layout: page title: Team +description: The development of Faker is guided by an international team. --- diff --git a/docs/about/team/TeamMember.ts b/docs/about/team/TeamMember.ts deleted file mode 100644 index 01fe3771..00000000 --- a/docs/about/team/TeamMember.ts +++ /dev/null @@ -1,7 +0,0 @@ -export interface Member { - readonly name: string; - readonly github: string; - readonly gitlab?: string; - readonly twitter?: string; - readonly roles: readonly string[]; -} diff --git a/docs/about/team/TeamMember.vue b/docs/about/team/TeamMember.vue deleted file mode 100644 index 03514a1f..00000000 --- a/docs/about/team/TeamMember.vue +++ /dev/null @@ -1,76 +0,0 @@ - - - - - diff --git a/docs/about/team/TeamPage.vue b/docs/about/team/TeamPage.vue index 99801f17..67171917 100644 --- a/docs/about/team/TeamPage.vue +++ b/docs/about/team/TeamPage.vue @@ -1,60 +1,41 @@ - - - + + + + + + + diff --git a/docs/about/team/members.json b/docs/about/team/members.json index 31018175..7732eab2 100644 --- a/docs/about/team/members.json +++ b/docs/about/team/members.json @@ -1,77 +1,141 @@ { "core": [ { + "avatar": "https://github.com/Shinigami92.png", "name": "Christopher Quadflieg", - "github": "Shinigami92", - "twitter": "Shini_92", - "roles": ["Code Maintainer"] + "title": "Code Maintainer", + "org": "Faker", + "orgLink": "https://fakerjs.dev", + "desc": "Passionate TypeScript enthusiast. Also core member of Vite.", + "links": [ + { "icon": "github", "link": "https://github.com/Shinigami92" }, + { "icon": "twitter", "link": "https://twitter.com/Shini_92" } + ], + "sponsor": "https://github.com/sponsors/Shinigami92" }, { + "avatar": "https://github.com/damienwebdev.png", "name": "Damien Retzinger", - "github": "damienwebdev", - "twitter": "damienwebdev", - "roles": ["Advisor"] + "title": "Advisor", + "org": "", + "orgLink": "", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/damienwebdev" }, + { "icon": "twitter", "link": "https://twitter.com/damienwebdev" } + ], + "sponsor": "https://github.com/sponsors/damienwebdev" }, { + "avatar": "https://github.com/prisis.png", "name": "Daniel Bannert", - "github": "prisis", - "twitter": "_prisis_", - "roles": ["Organization Owner"] + "title": "Organization Owner", + "org": "", + "orgLink": "", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/prisis" }, + { "icon": "twitter", "link": "https://twitter.com/_prisis_" } + ], + "sponsor": "https://github.com/sponsors/prisis" }, { + "avatar": "https://github.com/ST-DDT.png", "name": "Daniel Theuke", - "github": "ST-DDT", - "roles": ["Code Maintainer", "Docs Automation"] + "title": "Code Maintainer | Docs Automation", + "org": "", + "orgLink": "", + "desc": "", + "links": [{ "icon": "github", "link": "https://github.com/ST-DDT" }], + "sponsor": "https://github.com/sponsors/ST-DDT" }, { + "avatar": "https://github.com/clarkerican.png", "name": "Erica Clark", - "github": "clarkerican", - "twitter": "clarkerican", - "roles": [] + "title": "", + "org": "", + "orgLink": "", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/clarkerican" }, + { "icon": "twitter", "link": "https://twitter.com/clarkerican" } + ] }, { + "avatar": "https://github.com/griest024.png", "name": "griest", - "github": "griest024", - "gitlab": "griest", - "roles": ["Code Reviewer"] + "title": "Code Reviewer", + "org": "", + "orgLink": "", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/griest024" }, + { "icon": "gitlab", "link": "https://gitlab.com/griest" } + ] }, { + "avatar": "https://github.com/JessicaSachs.png", "name": "Jessica Sachs", - "github": "JessicaSachs", - "twitter": "_JessicaSachs", - "roles": ["Press Officer"] + "title": "Press Officer", + "org": "", + "orgLink": "", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/JessicaSachs" }, + { "icon": "twitter", "link": "https://twitter.com/_JessicaSachs" } + ], + "sponsor": "https://github.com/sponsors/JessicaSachs" } ], "contributors": [ { + "avatar": "https://github.com/import-brain.png", "name": "Eric Cheng", - "github": "import-brain", - "roles": ["Triage", "Contributor"] + "title": "Triage", + "org": "", + "orgLink": "", + "desc": "", + "links": [{ "icon": "github", "link": "https://github.com/import-brain" }] }, { + "avatar": "https://github.com/xDivisionByZerox.png", "name": "Leyla Jรคhnig", - "github": "xDivisionByZerox", - "roles": ["Contributor"] + "title": "Contributor", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/xDivisionByZerox" } + ] }, { + "avatar": "https://github.com/pkuczynski.png", "name": "Piotr Kuczynski", - "github": "pkuczynski", - "twitter": "PiotrKuczynski", - "roles": ["Contributor"] + "title": "Contributor", + "org": "", + "orgLink": "", + "desc": "", + "links": [ + { "icon": "github", "link": "https://github.com/pkuczynski" }, + { "icon": "twitter", "link": "https://twitter.com/PiotrKuczynski" } + ], + "sponsor": "https://github.com/sponsors/pkuczynski" } ], - "previous": [ + "emeriti": [ { + "avatar": "https://github.com/MateusDadalto.png", "name": "Mateus Dadalto", - "github": "MateusDadalto", - "twitter": "MateusD", - "roles": [] + "links": [ + { "icon": "github", "link": "https://github.com/MateusDadalto" }, + { "icon": "twitter", "link": "https://twitter.com/MateusD" } + ] }, { + "avatar": "https://github.com/mmahalwy.png", "name": "Mo Mahallawy", - "github": "mmahalwy", - "twitter": "mmahalwy", - "roles": [] + "links": [ + { "icon": "github", "link": "https://github.com/mmahalwy" }, + { "icon": "twitter", "link": "https://twitter.com/mmahalwy" } + ] } ] } diff --git a/docs/guide/migration-guide-v5.md b/docs/guide/migration-guide-v5.md new file mode 100644 index 00000000..1fcc229f --- /dev/null +++ b/docs/guide/migration-guide-v5.md @@ -0,0 +1,85 @@ +# Migrating from Faker v5 to v6 + +[[toc]] + +### ESM Support + +**New Format**: We're now ESM compatible! We've dropped the Browser bundle in favor of ESM. + +So if you'd like to use `Faker` in the **browser**, simply include it using a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#applying_the_module_to_your_html). + +```html + +``` + +### Remove all references to `faker` from your project. The new package is located at `@faker-js/faker` + +:::warning +You **MUST** swap all references from the `faker` package to the new `@faker-js/faker` package. + +In addition to releasing all _future_ versions under the `@faker-js/faker` package namespace, we have also provided all _historical_ versions of Faker. + +If you depend on a specific version of Faker you still can reference the version directly. + +`npm i @faker-js/faker@5.5.3 -D` will work just fine ๐Ÿ˜„. +::: + +### TypeScript + +:::tip TypeScript Improvements +Faker now ships with its own types! Remove `@types/faker` from your `package.json` to avoid conflicts. +::: + +### Tree-shaking + +:::warning +Tree shaking is not yet fully supported due to some structural issues. But we plan to make Faker fully tree-shakable in the future. +::: + +For now Faker supports tree-shaking for some parts, and we highly recommend that you take advantage of your bundler's tree-shaking capabilities and change how you import Faker right now. + +Instead of using: + +```ts +// js +const faker = require('@faker-js/faker'); + +// ts +import faker from '@faker-js/faker'; +``` + +You should switch to: + +```ts +// js +const { faker } = require('@faker-js/faker'); + +// ts +import { faker } from '@faker-js/faker'; +``` + +If you only need one specific language, we highly recommend to make use of the locale specific imports like: + +```ts +// js +const fakerDe = require('@faker-js/faker/locale/de'); + +// ts +import fakerDe from '@faker-js/faker/locale/de'; +``` + +This is especially true if you're importing Faker in the browser. + +Faker is a giant package made up of many megabytes of strings. Only import what you need. + +_We plan to load the locales in another way in a future major release._ + +--- + +Happy Faking! + +- Shini, Jess, and the Faker Team diff --git a/docs/index.md b/docs/index.md index 7a4b9300..8f5f6b55 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,27 +1,38 @@ --- -home: true -title: 'Faker' -heroImage: /logo.svg -heroAlt: 'Cartoon logo of a panda magician' -heroText: 'Faker' -tagline: 'Generate massive amounts of fake (but realistic) data for testing and development.' -actionText: Get Started -actionLink: /guide/ -altActionText: Star -altActionLink: https://github.com/faker-js/faker +layout: home + +hero: + name: Faker + text: '' + tagline: Generate massive amounts of fake (but realistic) data for testing and development. + image: + src: /logo.svg + alt: Cartoon logo of a panda magician + actions: + - theme: brand + text: Get Started + link: /guide/ + - theme: alt + text: View on GitHub + link: https://github.com/faker-js/faker features: - - title: ๐Ÿ‘  Products + - icon: ๐Ÿ‘  + title: Products details: Generate Prices, Product Names, Adjectives, and Descriptions. - - title: ๐Ÿ’ธ Finance + - icon: ๐Ÿ’ธ + title: Finance details: Create stubbed out Account Details, Transactions, and Crypto Addresses. - - title: ๐Ÿ’Œ Addresses + - icon: ๐Ÿ’Œ + title: Addresses details: Generate valid Addresses, Zip Codes, Street Names, States, and Countries! - - title: ๐Ÿ‘พ Hacker Jargon + - icon: ๐Ÿ‘พ + title: Hacker Jargon details: โ€œTry to reboot the SQL bus, maybe it will bypass the virtual application!โ€ - - title: โฐ Time-based Data + - icon: โฐ + title: Time-based Data details: Past, present, future, recent, soon... whenever! - - title: ๐ŸŒ Localization + - icon: ๐ŸŒ + title: Localization details: Set a locale to generate realistic looking Names, Addresses, and Phone Numbers. -footer: MIT Licensed 2022 --- diff --git a/docs/migration-guide-v5/index.md b/docs/migration-guide-v5/index.md deleted file mode 100644 index 1fcc229f..00000000 --- a/docs/migration-guide-v5/index.md +++ /dev/null @@ -1,85 +0,0 @@ -# Migrating from Faker v5 to v6 - -[[toc]] - -### ESM Support - -**New Format**: We're now ESM compatible! We've dropped the Browser bundle in favor of ESM. - -So if you'd like to use `Faker` in the **browser**, simply include it using a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#applying_the_module_to_your_html). - -```html - -``` - -### Remove all references to `faker` from your project. The new package is located at `@faker-js/faker` - -:::warning -You **MUST** swap all references from the `faker` package to the new `@faker-js/faker` package. - -In addition to releasing all _future_ versions under the `@faker-js/faker` package namespace, we have also provided all _historical_ versions of Faker. - -If you depend on a specific version of Faker you still can reference the version directly. - -`npm i @faker-js/faker@5.5.3 -D` will work just fine ๐Ÿ˜„. -::: - -### TypeScript - -:::tip TypeScript Improvements -Faker now ships with its own types! Remove `@types/faker` from your `package.json` to avoid conflicts. -::: - -### Tree-shaking - -:::warning -Tree shaking is not yet fully supported due to some structural issues. But we plan to make Faker fully tree-shakable in the future. -::: - -For now Faker supports tree-shaking for some parts, and we highly recommend that you take advantage of your bundler's tree-shaking capabilities and change how you import Faker right now. - -Instead of using: - -```ts -// js -const faker = require('@faker-js/faker'); - -// ts -import faker from '@faker-js/faker'; -``` - -You should switch to: - -```ts -// js -const { faker } = require('@faker-js/faker'); - -// ts -import { faker } from '@faker-js/faker'; -``` - -If you only need one specific language, we highly recommend to make use of the locale specific imports like: - -```ts -// js -const fakerDe = require('@faker-js/faker/locale/de'); - -// ts -import fakerDe from '@faker-js/faker/locale/de'; -``` - -This is especially true if you're importing Faker in the browser. - -Faker is a giant package made up of many megabytes of strings. Only import what you need. - -_We plan to load the locales in another way in a future major release._ - ---- - -Happy Faking! - -- Shini, Jess, and the Faker Team -- cgit v1.2.3