From 7cfe0f05ab013904c66c48d8529d2ba4747869cb Mon Sep 17 00:00:00 2001 From: Kia King Ishii Date: Wed, 22 Jun 2022 20:06:53 +0900 Subject: [PATCH] feat(theme): add team page feature (#828) --- docs/.vitepress/config.ts | 3 +- docs/guide/migration-from-vitepress-0.md | 2 +- .../{theme-homepage.md => theme-home-page.md} | 2 +- docs/guide/theme-introduction.md | 8 +- docs/guide/theme-layout.md | 2 +- docs/guide/theme-team-page.md | 255 ++++++++++++++++++ .../components/VPTeamMembers.vue | 55 ++++ .../components/VPTeamMembersItem.vue | 215 +++++++++++++++ .../theme-default/components/VPTeamPage.vue | 53 ++++ .../components/VPTeamPageSection.vue | 77 ++++++ .../components/VPTeamPageTitle.vue | 63 +++++ src/client/theme-default/index.ts | 4 + .../styles/components/vp-doc.css | 25 +- theme.d.ts | 4 + types/default-theme.d.ts | 13 + 15 files changed, 773 insertions(+), 8 deletions(-) rename docs/guide/{theme-homepage.md => theme-home-page.md} (99%) create mode 100644 docs/guide/theme-team-page.md create mode 100644 src/client/theme-default/components/VPTeamMembers.vue create mode 100644 src/client/theme-default/components/VPTeamMembersItem.vue create mode 100644 src/client/theme-default/components/VPTeamPage.vue create mode 100644 src/client/theme-default/components/VPTeamPageSection.vue create mode 100644 src/client/theme-default/components/VPTeamPageTitle.vue diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 23eeac47de9..94315e62021 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -87,7 +87,8 @@ function sidebarGuide() { { text: 'Edit Link', link: '/guide/theme-edit-link' }, { text: 'Last Updated', link: '/guide/theme-last-updated' }, { text: 'Layout', link: '/guide/theme-layout' }, - { text: 'Homepage', link: '/guide/theme-homepage' }, + { text: 'Home Page', link: '/guide/theme-home-page' }, + { text: 'Team Page', link: '/guide/theme-team-page' }, { text: 'Footer', link: '/guide/theme-footer' }, { text: 'Search', link: '/guide/theme-search' }, { text: 'Carbon Ads', link: '/guide/theme-carbon-ads' } diff --git a/docs/guide/migration-from-vitepress-0.md b/docs/guide/migration-from-vitepress-0.md index 80c5803fa71..f7041dc85a2 100644 --- a/docs/guide/migration-from-vitepress-0.md +++ b/docs/guide/migration-from-vitepress-0.md @@ -19,5 +19,5 @@ If you're coming from VitePress 0.x version, there're several breaking changes d ## Frontmatter Config -- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Homepage guide](./theme-homepage) for details. +- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](./theme-home-page) for details. - `footer` option is moved to [`themeConfig.footer`](../config/theme-configs#footer). diff --git a/docs/guide/theme-homepage.md b/docs/guide/theme-home-page.md similarity index 99% rename from docs/guide/theme-homepage.md rename to docs/guide/theme-home-page.md index 4de188adc06..80a880086ac 100644 --- a/docs/guide/theme-homepage.md +++ b/docs/guide/theme-home-page.md @@ -1,4 +1,4 @@ -# Homepage +# Home Page VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter). diff --git a/docs/guide/theme-introduction.md b/docs/guide/theme-introduction.md index f886cf8b2cd..09d56d66778 100644 --- a/docs/guide/theme-introduction.md +++ b/docs/guide/theme-introduction.md @@ -8,16 +8,17 @@ VitePress comes with its default theme providing many features out of the box. L - [Edit Link](./theme-edit-link) - [Last Updated](./theme-last-updated) - [Layout](./theme-layout) -- [Homepage](./theme-homepage) +- [Home Page](./theme-home-page) +- [Team Page](./theme-team-page) - [Footer](./theme-footer) - [Search](./theme-search) - [Carbon Ads](./theme-carbon-ads) -If you don't find the features you're looking for, or you would rather create your own theme, you may customize VitePress to fit your requirements. +If you don't find the features you're looking for, or you would rather create your own theme, you may customize VitePress to fit your requirements. In the following sections, we'll go through each way of customizing the VitePress theme. ## Using a Custom Theme -You can enable a custom theme by adding the `.vitepress/theme/index.js` file (the "theme entry file"). +You can enable a custom theme by adding the `.vitepress/theme/index.js` or `.vitepress/theme/index.ts` file (the "theme entry file"). ``` . @@ -53,6 +54,7 @@ The theme entry file should export the theme as its default export: import Layout from './Layout.vue' export default { + // root component to wrap each page Layout, // this is a Vue 3 functional component diff --git a/docs/guide/theme-layout.md b/docs/guide/theme-layout.md index 8ea0c5f6e56..33033102c31 100644 --- a/docs/guide/theme-layout.md +++ b/docs/guide/theme-layout.md @@ -35,4 +35,4 @@ Note that even in this layout, sidebar will still show up if the page has a matc ## Home Layout -Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-homepage) for more details. +Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-home-page) for more details. diff --git a/docs/guide/theme-team-page.md b/docs/guide/theme-team-page.md new file mode 100644 index 00000000000..f19b52d5775 --- /dev/null +++ b/docs/guide/theme-team-page.md @@ -0,0 +1,255 @@ + + +# Team Page + +If you would like to introduce your team, you may use Team components to construct the Team Page. There're 2 ways of using these components. One is to embbed it in doc page, and another is to create a full Team Page. + +## Show team members in a page + +You may use `` component exposed from `vitepress/theme` to display a list of team members on any page. + +```html + + +# Our Team + +Say hello to our awesome team. + + +``` + +The above will display a team member in card looking element. It should display something similar to below. + + + +`` component comes in 2 different sizes, `small` and `medium`. While it boiles down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [``](#vpteammembers). + +Embbeding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a refference to documenation context. + +If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page). + +## Create a full Team Page + +Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./theme-home-page). + +To create a team page, first, create a new md file. The file name doesn't matter, but here lets call it `team.md`. In this file, set frontmatter option `layout: page`, and then you may compose your page structure using `TeamPage` components. + +```html +--- +layout: page +--- + + + + + + + + + +``` + +When creating a full team page, remember to wrap all components with `` component. This component will ensure all nested team related components get the proper layout structure like spacings. + +`` component adds the page title section. The title being `

` heading. Use `#title` and `#lead` slot to document about your team. + +`` works as same as when used in a doc page. It will display list of members. + +### Add sections to divide team members + +You may add "sections" to the team page. For example, you may have different types of team members such as Core Team Members and Community Partners. You can devide these members into sections to better explain the roles of each group. + +To do so, add `` component to the `team.md` file we created previously. + +```html +--- +layout: page +--- + + + + + + + + + + + + + + +``` + +The `` component can have `#title` and `#lead` slot similar to `VPTeamPageTitle` component, and also `#members` slot for displaying team members. + +Remember to put in `` component within `#members` slot. + +## `` + +The `` component displays a given list of members. + +```html + +``` + +```ts +interface Props { + // Size of each members. Defaults to `medium`. + size?: 'small' | 'meidum' + + // List of members to display. + members: TeamMember[] +} + +interface TeamMember { + // Avatar image for the member. + avatar: string + + // Name of the member. + name: string + + // Title to be shown below member's name. + // e.g. Developer, Software Engineer, etc. + title?: string + + // Organization that the member belongs. + org?: string + + // URL for the organization. + orgLink?: string + + // Description for the member. + desc?: string + + // Social links. e.g. GitHub, Twitter, etc. You may pass in + // the Social Links object here. + // See: https://vitepress.vuejs.org/config/theme-configs.html#sociallinks + links?: SocialLink[] + + // URL for the sponsor page for the member. + sponsor?: string +} +``` + +## `` + +The root component when creating a full team page. It only accepts a single slot. It's will style all passed in team related components. + +## `` + +Adds "title" section of the page. Best use at the very beginning under ``. It accepts `#title` and `#lead` slot. + +```html + + + + + + +``` + +## `` + +Creates a "section" with in team page. It accepts `#title`, `#lead`, and `#members` slot. You may add as many sections as you like inside ``. + +```html + + ... + + + + + + +``` diff --git a/src/client/theme-default/components/VPTeamMembers.vue b/src/client/theme-default/components/VPTeamMembers.vue new file mode 100644 index 00000000000..c7416948d43 --- /dev/null +++ b/src/client/theme-default/components/VPTeamMembers.vue @@ -0,0 +1,55 @@ + + + + + diff --git a/src/client/theme-default/components/VPTeamMembersItem.vue b/src/client/theme-default/components/VPTeamMembersItem.vue new file mode 100644 index 00000000000..dfec1760a8b --- /dev/null +++ b/src/client/theme-default/components/VPTeamMembersItem.vue @@ -0,0 +1,215 @@ + + + + + diff --git a/src/client/theme-default/components/VPTeamPage.vue b/src/client/theme-default/components/VPTeamPage.vue new file mode 100644 index 00000000000..6af86f2e297 --- /dev/null +++ b/src/client/theme-default/components/VPTeamPage.vue @@ -0,0 +1,53 @@ + + + diff --git a/src/client/theme-default/components/VPTeamPageSection.vue b/src/client/theme-default/components/VPTeamPageSection.vue new file mode 100644 index 00000000000..d3150140096 --- /dev/null +++ b/src/client/theme-default/components/VPTeamPageSection.vue @@ -0,0 +1,77 @@ + + + diff --git a/src/client/theme-default/components/VPTeamPageTitle.vue b/src/client/theme-default/components/VPTeamPageTitle.vue new file mode 100644 index 00000000000..9751a1886aa --- /dev/null +++ b/src/client/theme-default/components/VPTeamPageTitle.vue @@ -0,0 +1,63 @@ + + + diff --git a/src/client/theme-default/index.ts b/src/client/theme-default/index.ts index 4b4be0462ef..7b792128358 100644 --- a/src/client/theme-default/index.ts +++ b/src/client/theme-default/index.ts @@ -15,6 +15,10 @@ export { default as VPHomeHero } from './components/VPHomeHero.vue' export { default as VPHomeFeatures } from './components/VPHomeFeatures.vue' export { default as VPHomeSponsors } from './components/VPHomeSponsors.vue' export { default as VPDocAsideSponsors } from './components/VPDocAsideSponsors.vue' +export { default as VPTeamPage } from './components/VPTeamPage.vue' +export { default as VPTeamPageTitle } from './components/VPTeamPageTitle.vue' +export { default as VPTeamPageSection } from './components/VPTeamPageSection.vue' +export { default as VPTeamMembers } from './components/VPTeamMembers.vue' const theme: Theme = { Layout, diff --git a/src/client/theme-default/styles/components/vp-doc.css b/src/client/theme-default/styles/components/vp-doc.css index e43aa8f3bf3..29128d3a43f 100644 --- a/src/client/theme-default/styles/components/vp-doc.css +++ b/src/client/theme-default/styles/components/vp-doc.css @@ -20,7 +20,7 @@ } .vp-doc h2 { - margin: 48px 0 0; + margin: 48px 0 16px; border-top: 1px solid var(--vp-c-divider-light); padding-top: 24px; letter-spacing: -0.02em; @@ -461,3 +461,26 @@ .vp-doc [class~='language-tsx']:before { content: 'tsx'; } .vp-doc [class~='language-vue']:before { content: 'vue'; } .vp-doc [class~='language-yaml']:before { content: 'yaml'; } + +/** + * Component: Team + * -------------------------------------------------------------------------- */ + +.vp-doc .VPTeamMembers { + margin-top: 24px; +} + +.vp-doc .VPTeamMembers.small.count-1 .container { + margin: 0 !important; + max-width: calc((100% - 24px) / 2) !important; +} + +.vp-doc .VPTeamMembers.small.count-2 .container, +.vp-doc .VPTeamMembers.small.count-3 .container { + max-width: 100% !important; +} + +.vp-doc .VPTeamMembers.medium.count-1 .container { + margin: 0 !important; + max-width: calc((100% - 24px) / 2) !important; +} diff --git a/theme.d.ts b/theme.d.ts index f53cbc936af..c0da7d5b631 100644 --- a/theme.d.ts +++ b/theme.d.ts @@ -5,6 +5,10 @@ export const VPHomeHero = ComponentOptions export const VPHomeFeatures = ComponentOptions export const VPHomeSponsors = ComponentOptions export const VPDocAsideSponsors = ComponentOptions +export const VPTeamPage = ComponentOptions +export const VPTeamPageTitle = ComponentOptions +export const VPTeamPageSection = ComponentOptions +export const VPTeamMembers = ComponentOptions declare const theme: { Layout: ComponentOptions diff --git a/types/default-theme.d.ts b/types/default-theme.d.ts index 26c02dfda32..52503b58c4e 100644 --- a/types/default-theme.d.ts +++ b/types/default-theme.d.ts @@ -181,6 +181,19 @@ export namespace DefaultTheme { copyright?: string } + // team ---------------------------------------------------------------------- + + export interface TeamMember { + avatar: string + name: string + title?: string + org?: string + orgLink?: string + desc?: string + links?: SocialLink[] + sponsor?: string + } + // locales ------------------------------------------------------------------- export interface LocaleLinks {