From 6f8f534cb9e95b00f6e69ed3fd0f89f1903e1099 Mon Sep 17 00:00:00 2001 From: Hossein Mehrabi Date: Tue, 12 Dec 2023 19:01:22 +0330 Subject: [PATCH] docs: update documentation MDX components: JobsPerDepartment, ExternalResourceCard, AssetCard Preset: add documentation for jobList generated file --- packages/logos-docusaurus-preset/README.md | 27 ++ packages/logos-docusaurus-theme/COMPONENTS.MD | 434 ------------------ packages/logos-docusaurus-theme/README.md | 154 +++++-- .../components/mdx/AssetCard/AssetCard.tsx | 30 ++ .../ExternalResourceCard.tsx | 37 ++ .../JobsPerDepartment/JobsPerDepartment.tsx | 23 +- 6 files changed, 239 insertions(+), 466 deletions(-) delete mode 100644 packages/logos-docusaurus-theme/COMPONENTS.MD diff --git a/packages/logos-docusaurus-preset/README.md b/packages/logos-docusaurus-preset/README.md index 5f15c3b..b15bbef 100644 --- a/packages/logos-docusaurus-preset/README.md +++ b/packages/logos-docusaurus-preset/README.md @@ -6,6 +6,8 @@ - [Supported Themes](#supported-themes) - [OpenGraph Image Generator](#opengraph-image-generator) - [Local Search](#local-search) + - [Generated Files](#generated-files) + - [Job Openings](#job-openings) - [Docs Plugin](#docs-plugin) - [Pages Plugin](#pages-plugin) - [Blog Plugin](#blog-plugin) @@ -191,6 +193,31 @@ presets: [ To learn more on how the plugin works, please visit the [plugin documentation](../docusaurus-search-local/README.md). +### Generated Files + +#### Job Openings + +Use the `generated.jobList` option to fetch job openings from the Greenhouse API for a specific job board. Each time you run `yarn start` or `yarn build`, the plugin will fetch the latest job openings from the Greenhouse API and generate a JSON file containing the job openings for the specified job board. The generated file will be located at `static/generated/jobs.json`. + +```js +presets: [ + [ + '@acid-info/logos-docusaurus-preset', + /** @type {import('@acid-info/logos-docusaurus-preset').PluginOptions} */ + ({ + businessUnit: 'Logos', + generated: { + jobList: { + jobBoard: 'your-job-board-id', + }, + }, + }), + ], +], +``` + +You can import the generated file in your website's code and use it to display the job openings. For example, you can use the `JobsPerDepartment` component from the [Logos theme](../logos-docusaurus-theme/README.md#jobsperdepartment) to display the job openings per department. + ### Docs Plugin The Docs plugin (Official Docusaurus Docs Plugin) is enabled by default and simplifies the creation and management of documentation on your website. To disable this plugin, set `docs` to `false` in your preset configuration. diff --git a/packages/logos-docusaurus-theme/COMPONENTS.MD b/packages/logos-docusaurus-theme/COMPONENTS.MD deleted file mode 100644 index 874d5c8..0000000 --- a/packages/logos-docusaurus-theme/COMPONENTS.MD +++ /dev/null @@ -1,434 +0,0 @@ -### AppCard - -A card component for displaying information about an app. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| ----------- | -------------- | -------- | ------- | ------------------------------------------- | -| logoSrc | string | false | | The source URL for the light logo image | -| logoSrcDark | string | false | | The source URL for the dark logo image | -| name | ReactReactNode | false | | The name of the app | -| description | ReactReactNode | false | | The description of the app | -| link | string | false | | The URL to link to when the card is clicked | -| linkLabel | string | false | | The label for the link to the app | - -**Example usage:** - -```jsx -import { AppCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; -``` - -**Grid example:** - -```jsx -import { - Grid, - AppCard, -} from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - - - - - - - -``` - -### Box - -A box component that can be used to add top and bottom margins with breakpoints. -**Props** - -| Prop Name | Type | Required | Default | Description | -| --------- | ---------------------------------- | -------- | ------- | ----------- | -| top | BreakpointsStyle \| number | false | 0 | | -| bottom | BreakpointsStyle \| number | false | 0 | | -| style | undefined | false | {} | undefined | - -```tsx -import { Box } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; -

This is some content inside the box.

- -``` - -### CallToActionButton - -A call-to-action button that can be used in MDX pages. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| --------- | ---------------------- | -------- | -------- | --------------------------------------------- | ---------------------- | -| href | string | false | | The URL to link to when the button is clicked | -| size | 'small' \| 'medium' | 'large' | false | 'large' | The size of the button | -| variant | ButtonProps['variant'] | false | 'filled' | The variant of the button | - -```jsx -import { CallToActionButton } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - Join our community - -``` - -### CallToActionSection - -A call-to-action section component that can be used in MDX pages. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| ----------- | ----------------------------------- | -------- | ---------- | --------------------------------------------------------- | -| title | ReactReactNode | false | | The title of the section | -| description | ReactReactNode | false | | The description of the section | -| columns | 1 \| 2 | false | 1 | The number of columns to display the content in | -| href | string | false | | The URL to link to when the button is clicked | -| label | string | false | | The label to display on the button | -| target | ReactAnchorHTMLAttributes['target'] | false | | The target attribute for the link e.g., `_self`, `_blank` | -| variant | ButtonProps['variant'] | false | 'outlined' | The variant of the button | -| list | Array | false | [] | A list of items to display in the section | - -```tsx -import { CallToActionSection } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; -``` - -With a list: - -```tsx -import { CallToActionSection } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - Follow the detailed -
- step-by-step guide here - - } - list={[ - { - title: 'Simple setup', - description: - 'Run integrated Nimbus Beacon Node and Validator Client together.', - }, - { - title: 'Use Nimbus Beacon node', - description: - 'Run Nimbus Beacon Node with an alternative validator client.', - }, - { - title: 'Use Nimbus Validator client', - description: - 'Run Nimbus Validator Client with an alternative Beacon Node', - }, - ]} - label="Get Nimbus" - target="_blank" - href="https://nimbus.guide/quick-start.html" -/> -``` - -### FeatureList - -A component that displays a list of features with titles and descriptions. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| --------- | ----------------- | -------- | ---------- | ------------------------------------------------- | -| title | ReactReactNode | false | 'Features' | The title of the feature list. | -| features | Array | false | [] | An array of features to be displayed in the list. | -| alignment | 'bottom' \| 'top' | false | 'bottom' | The vertical alignment of feature description. | - -```tsx -import { FeatureList } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - - Read More - - -``` - -### Hero - -A hero component that displays a large banner at the top of a page. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| --------- | ------------------- | -------- | ------- | ----------- | --- | -| size | 'large' \| 'medium' | 'small' | false | 'medium' | | - -```tsx -import { - Hero, - HeroTitle, - HeroDescription, - HeroVideo, - HeroActions, - HeroAction, -} from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - - - {'Light and Performant Clients, for All Ethereum Validators'} - - - { - 'Ethereum validators of all sizes trust Nimbus to run their nodes. From large node operators, to solo stakers on a Raspberry Pi.' - } - - - - Get Nimbus - - - - - - - - - -``` - -### PageCard - -A card component used in Docusaurus auto-generated category index pages to display page links. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| ----------- | -------------- | -------- | ------------------------------ | ----------- | -| title | ReactReactNode | false | | | -| description | ReactReactNode | false | | | -| icon | ReactReactNode | false | | | -| target | undefined | false | '\_self' | undefined | - -```tsx -import { PageCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; -``` - -### ProfileCard - -A component used to display team members' profiles, including their name, avatar, and social links. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| --------------- | ------ | -------- | ------- | ----------- | -| imgSrc | string | false | | | -| name | string | false | | | -| githubUsername | string | false | | | -| githubLink | string | false | | | -| discordUsername | string | false | | | -| discordLink | string | false | | | - -```tsx -import { ProfileCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; -``` - -Example usage of ProfileCard within a grid: - -```tsx -import { - Grid, - ProfileCard, -} from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - - - - Add more ProfileCard items within the grid - -``` - -### SocialCard - -A component used for displaying social media or community platform cards with a logo and description. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| ----------- | -------------- | -------- | ------- | ----------------------------------------------------------------------------------- | -| logoSrc | string | false | | The URL of the logo image for the social media or community platform (light theme). | -| logoSrcDark | string | false | | The URL of the logo image for the social media or community platform (dark theme). | -| description | ReactReactNode | false | | The description or content associated with the social media or community platform. | - -```tsx -import { SocialCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; -``` - -Grid example: - -```tsx -import { - Box, - Grid, - SocialCard, -} from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - - - - - - - - - -``` - -### TimelineItem - -A component for displaying roadmap items, such as events or milestones, in a timeline layout. - -**Props** - -| Prop Name | Type | Required | Default | Description | -| ----------- | ------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- | -------------------------------------- | -| index | ReactReactNode | true | | The index or label of the timeline item. | -| alignment | 'top' \| 'bottom' | false | 'top' | The alignment of the timeline item, either 'top' or 'bottom'. (Optional, default: 'top') | -| period | ReactReactNode | true | | The period or time frame associated with the timeline item. e.g., `2023 Q3` | -| description | ReactReactNode | true | | The description or content of the timeline item. | -| borderStyle | 'solid' \| 'dashed' | 'none' | false | | The border style for the timeline item | - -Roadmap example: - -```tsx -import { - Box, - Grid, - TimelineItem, - SectionHeader, - CallToActionButton, -} from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' -; - - - Read more - - } - > - - - - Add more items here - - - - - -``` diff --git a/packages/logos-docusaurus-theme/README.md b/packages/logos-docusaurus-theme/README.md index 958e336..800b018 100644 --- a/packages/logos-docusaurus-theme/README.md +++ b/packages/logos-docusaurus-theme/README.md @@ -11,11 +11,14 @@ - [How to Disable the Image Generator for a Specific Page:](#how-to-disable-the-image-generator-for-a-specific-page) - [MDX Components](#mdx-components) - [AppCard](#appcard) + - [AssetCard](#assetcard) - [Box](#box) - [CallToActionButton](#calltoactionbutton) - [CallToActionSection](#calltoactionsection) + - [ExternalResourceCard](#externalresourcecard) - [FeatureList](#featurelist) - [Hero](#hero) + - [JobsPerDepartment](#jobsperdepartment) - [PageCard](#pagecard) - [ProfileCard](#profilecard) - [SocialCard](#socialcard) @@ -219,6 +222,7 @@ A card component for displaying information about an app. ```jsx import { AppCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + ; ``` +### AssetCard + +A card component with an image preview and download buttons. + +**Props** + +| Prop Name | Type | Required | Default | Description | +| ------------- | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| title | ReactReactNode | false | | The title of the asset | +| previewSrc | string | true | | The source URL for the preview image | +| forceDownload | boolean | false | false | Whether to force download the asset when clicking on the preview image (default: false); if false, the asset might open in a new tab | +| downloadable | Array | false | | The list of downloadable assets | + +**Example usage:** + +```jsx +import { AssetCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + +; +``` + ### Box A box component that can be used to add top and bottom margins with breakpoints. **Props** -| Prop Name | Type | Required | Default | Description | -| --------- | ------------------------ | -------- | ------- | ----------- | --- | -| top | BreakpointsStyle | number | false | 0 | | -| bottom | BreakpointsStyle | number | false | 0 | | -| style | undefined | false | {} | undefined | +| Prop Name | Type | Required | Default | Description | +| --------- | ---------------------------------- | -------- | ------- | ----------- | +| top | BreakpointsStyle \| number | false | 0 | | +| bottom | BreakpointsStyle \| number | false | 0 | | +| style | undefined | false | {} | undefined | ```tsx import { Box } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' @@ -281,15 +314,15 @@ A call-to-action button that can be used in MDX pages. **Props** -| Prop Name | Type | Required | Default | Description | -| -------------- | ---------------------- | -------- | -------- | --------------------------------------------- | ------- | ---------------------- | -| href | string | false | | The URL to link to when the button is clicked | -| size | 'small' | 'medium' | 'large' | false | 'large' | The size of the button | -| @type {'small' | 'medium' | 'large'} | -| variant | ButtonProps['variant'] | false | 'filled' | The variant of the button | +| Prop Name | Type | Required | Default | Description | +| --------- | ---------------------- | -------- | -------- | --------------------------------------------- | ---------------------- | +| href | string | false | | The URL to link to when the button is clicked | +| size | 'small' \| 'medium' | 'large' | false | 'large' | The size of the button | +| variant | ButtonProps['variant'] | false | 'filled' | The variant of the button | ```jsx import { CallToActionButton } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + ; ``` +### ExternalResourceCard + +A card component with an optional image preview for displaying information about an external resource. + +**Props** + +| Prop Name | Type | Required | Default | Description | +| -------------- | -------------- | -------- | ------- | -------------------------------------------------- | +| logoSrc | string | false | | The source URL for logo image in light mode | +| logoSrcDark | string | false | | The source URL for logo image in dark mode | +| title | ReactReactNode | false | | The title of the external resource | +| description | ReactReactNode | false | | The description of the external resource | +| previewSrc | string | false | | The source URL for the preview image in light mode | +| previewSrcDark | string | false | | The source URL for the preview image in dark mode | + +**Example usage:** + +```jsx +import { ExternalResourceCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + + +``` + ### FeatureList A component that displays a list of features with titles and descriptions. **Props** -| Prop Name | Type | Required | Default | Description | -| --------- | -------------- | -------- | ---------- | ------------------------------------------------- | ---------------------------------------------- | -| title | ReactReactNode | false | 'Features' | The title of the feature list. | -| features | Array | false | [] | An array of features to be displayed in the list. | -| alignment | 'bottom' | 'top' | false | 'bottom' | The vertical alignment of feature description. | +| Prop Name | Type | Required | Default | Description | +| --------- | ----------------- | -------- | ---------- | ------------------------------------------------- | +| title | ReactReactNode | false | 'Features' | The title of the feature list. | +| features | Array | false | [] | An array of features to be displayed in the list. | +| alignment | 'bottom' \| 'top' | false | 'bottom' | The vertical alignment of feature description. | ```tsx import { FeatureList } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + ; @@ -447,6 +515,27 @@ import { ``` +### JobsPerDepartment + +A component for displaying job openings organized by department. The component requires a `jobData` prop that contains an array of departments, each with an array of jobs openings. If you're using our preset, this data is automatically fetched from Greenhouse API. To enable this, please refer to the [preset documentation](../logos-docusaurus-preset#xyz). + +**Props** + +| Prop Name | Type | Required | Default | Description | +| ------------ | --------- | -------- | ------- | ------------------------------------------------------------ | +| jobData | signature | true | | An array of departments, each with an array of job openings. | +| titleFilter | string | false | '' | A string to filter jobs by title. | +| useDummyData | boolean | false | false | Use dummy data instead of real data. | + +**Example usage:** + +```jsx +import * as jobData from '/static/generated/jobs.json' +import { JobsPerDepartment } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + +; +``` + ### PageCard A card component used in Docusaurus auto-generated category index pages to display page links. @@ -462,6 +551,7 @@ A card component used in Docusaurus auto-generated category index pages to displ ```tsx import { PageCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + ; @@ -577,13 +670,13 @@ A component for displaying roadmap items, such as events or milestones, in a tim **Props** -| Prop Name | Type | Required | Default | Description | -| ----------- | -------------- | -------- | ------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------- | -| index | ReactReactNode | true | | The index or label of the timeline item. | -| alignment | 'top' | 'bottom' | false | 'top' | The alignment of the timeline item, either 'top' or 'bottom'. (Optional, default: 'top') | -| period | ReactReactNode | true | | The period or time frame associated with the timeline item. e.g., `2023 Q3` | -| description | ReactReactNode | true | | The description or content of the timeline item. | -| borderStyle | 'solid' | 'dashed' | 'none' | false | | The border style for the timeline item | +| Prop Name | Type | Required | Default | Description | +| ----------- | ------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- | -------------------------------------- | +| index | ReactReactNode | true | | The index or label of the timeline item. | +| alignment | 'top' \| 'bottom' | false | 'top' | The alignment of the timeline item, either 'top' or 'bottom'. (Optional, default: 'top') | +| period | ReactReactNode | true | | The period or time frame associated with the timeline item. e.g., `2023 Q3` | +| description | ReactReactNode | true | | The description or content of the timeline item. | +| borderStyle | 'solid' \| 'dashed' | 'none' | false | | The border style for the timeline item | Roadmap example: @@ -595,6 +688,7 @@ import { SectionHeader, CallToActionButton, } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + ; , 'title'> & { + /** + * The title of the asset + */ title?: React.ReactNode + /** + * The source URL for the preview image + */ previewSrc: string + /** + * Whether to force download the asset when clicking on the preview image (default: false); if false, the asset might open in a new tab + */ forceDownload?: boolean + /** + * The list of downloadable assets + */ downloadable?: DownloadableAsset[] } +/** + * A card component with an image preview and download buttons. + * + * @example + * **Example usage:** + * ```jsx + * import { AssetCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + * + * + * ``` + */ export const AssetCard: React.FC = ({ title, previewSrc, diff --git a/packages/logos-docusaurus-theme/src/client/components/mdx/ExternalResourceCard/ExternalResourceCard.tsx b/packages/logos-docusaurus-theme/src/client/components/mdx/ExternalResourceCard/ExternalResourceCard.tsx index ba5ad9f..3ef41bf 100644 --- a/packages/logos-docusaurus-theme/src/client/components/mdx/ExternalResourceCard/ExternalResourceCard.tsx +++ b/packages/logos-docusaurus-theme/src/client/components/mdx/ExternalResourceCard/ExternalResourceCard.tsx @@ -10,14 +10,51 @@ export type ExternalResourceCardProps = Omit< React.HTMLProps, 'title' > & { + /** + * The source URL for logo image in light mode + */ logoSrc?: string + /** + * The source URL for logo image in dark mode + */ logoSrcDark?: string + /** + * The title of the external resource + */ title?: React.ReactNode + /** + * The description of the external resource + */ description?: React.ReactNode + /** + * The source URL for the preview image in light mode + * */ previewSrc?: string + /** + * The source URL for the preview image in dark mode + */ previewSrcDark?: string } +/** + * A card component with an optional image preview for displaying information about an external resource. + * + * @example + * **Example usage:** + * ```jsx + * import { ExternalResourceCard } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + * + * + * ``` + */ export const ExternalResourceCard: React.FC = ({ title, logoSrc, diff --git a/packages/logos-docusaurus-theme/src/client/components/mdx/JobsPerDepartment/JobsPerDepartment.tsx b/packages/logos-docusaurus-theme/src/client/components/mdx/JobsPerDepartment/JobsPerDepartment.tsx index f7eba87..3b36d12 100644 --- a/packages/logos-docusaurus-theme/src/client/components/mdx/JobsPerDepartment/JobsPerDepartment.tsx +++ b/packages/logos-docusaurus-theme/src/client/components/mdx/JobsPerDepartment/JobsPerDepartment.tsx @@ -63,16 +63,35 @@ const hasJobs = (jobsPerDepartment: JobDepartmentArray): boolean => { } type JobsPerDepartmentProps = React.HTMLAttributes & { + /** + * An array of departments, each with an array of job openings. + */ jobData: { departments?: JobDepartmentArray } + /** + * A string to filter jobs by title. + */ titleFilter?: string - fetchAll?: boolean + /** + * Use dummy data instead of real data. + */ useDummyData?: boolean } +/** + * A component for displaying job openings organized by department. The component requires a `jobData` prop that contains an array of departments, each with an array of jobs openings. If you're using our preset, this data is automatically fetched from Greenhouse API. To enable this, please refer to the [preset documentation](../logos-docusaurus-preset#job-openings). + * + * @example + * **Example usage:** + * ```jsx + * import * as jobData from '/static/generated/jobs.json' + * import { JobsPerDepartment } from '@acid-info/logos-docusaurus-theme/lib/client/components/mdx' + * + * + * ``` + */ export const JobsPerDepartment: React.FC = ({ jobData, titleFilter = '', - fetchAll = false, useDummyData = false, ...props }) => {