Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
refactor(docs,theme): split DocItem comp, useDoc hook (#7644)
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
- Loading branch information
Showing
17 changed files
with
357 additions
and
144 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
47 changes: 47 additions & 0 deletions
47
packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
import React from 'react'; | ||
import clsx from 'clsx'; | ||
import {ThemeClassNames, useDoc} from '@docusaurus/theme-common'; | ||
import Heading from '@theme/Heading'; | ||
import MDXContent from '@theme/MDXContent'; | ||
import type {Props} from '@theme/DocItem/Content'; | ||
|
||
/** | ||
Title can be declared inside md content or declared through | ||
front matter and added manually. To make both cases consistent, | ||
the added title is added under the same div.markdown block | ||
See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120 | ||
We render a "synthetic title" if: | ||
- user doesn't ask to hide it with front matter | ||
- the markdown content does not already contain a top-level h1 heading | ||
*/ | ||
function useSyntheticTitle(): string | null { | ||
const {metadata, frontMatter, contentTitle} = useDoc(); | ||
const shouldRender = | ||
!frontMatter.hide_title && typeof contentTitle === 'undefined'; | ||
if (!shouldRender) { | ||
return null; | ||
} | ||
return metadata.title; | ||
} | ||
|
||
export default function DocItemContent({children}: Props): JSX.Element { | ||
const syntheticTitle = useSyntheticTitle(); | ||
return ( | ||
<div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}> | ||
{syntheticTitle && ( | ||
<header> | ||
<Heading as="h1">{syntheticTitle}</Heading> | ||
</header> | ||
)} | ||
<MDXContent>{children}</MDXContent> | ||
</div> | ||
); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
67 changes: 67 additions & 0 deletions
67
packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
import React from 'react'; | ||
import clsx from 'clsx'; | ||
import {useWindowSize, useDoc} from '@docusaurus/theme-common'; | ||
import DocItemPaginator from '@theme/DocItem/Paginator'; | ||
import DocVersionBanner from '@theme/DocVersionBanner'; | ||
import DocVersionBadge from '@theme/DocVersionBadge'; | ||
import DocItemFooter from '@theme/DocItem/Footer'; | ||
import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile'; | ||
import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop'; | ||
import DocItemContent from '@theme/DocItem/Content'; | ||
import DocBreadcrumbs from '@theme/DocBreadcrumbs'; | ||
import type {Props} from '@theme/DocItem/Layout'; | ||
|
||
import styles from './styles.module.css'; | ||
|
||
/** | ||
* Decide if the toc should be rendered, on mobile or desktop viewports | ||
*/ | ||
function useDocTOC() { | ||
const {frontMatter, toc} = useDoc(); | ||
const windowSize = useWindowSize(); | ||
|
||
const hidden = frontMatter.hide_table_of_contents; | ||
const canRender = !hidden && toc.length > 0; | ||
|
||
const mobile = canRender ? <DocItemTOCMobile /> : undefined; | ||
|
||
const desktop = | ||
canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? ( | ||
<DocItemTOCDesktop /> | ||
) : undefined; | ||
|
||
return { | ||
hidden, | ||
mobile, | ||
desktop, | ||
}; | ||
} | ||
|
||
export default function DocItemLayout({children}: Props): JSX.Element { | ||
const docTOC = useDocTOC(); | ||
return ( | ||
<div className="row"> | ||
<div className={clsx('col', !docTOC.hidden && styles.docItemCol)}> | ||
<DocVersionBanner /> | ||
<div className={styles.docItemContainer}> | ||
<article> | ||
<DocBreadcrumbs /> | ||
<DocVersionBadge /> | ||
{docTOC.mobile} | ||
<DocItemContent>{children}</DocItemContent> | ||
<DocItemFooter /> | ||
</article> | ||
<DocItemPaginator /> | ||
</div> | ||
</div> | ||
{docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>} | ||
</div> | ||
); | ||
} |
17 changes: 17 additions & 0 deletions
17
packages/docusaurus-theme-classic/src/theme/DocItem/Layout/styles.module.css
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
.docItemContainer header + *, | ||
.docItemContainer article > *:first-child { | ||
margin-top: 0; | ||
} | ||
|
||
@media (min-width: 997px) { | ||
.docItemCol { | ||
max-width: 75% !important; | ||
} | ||
} |
21 changes: 21 additions & 0 deletions
21
packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
import React from 'react'; | ||
import {PageMetadata, useDoc} from '@docusaurus/theme-common'; | ||
|
||
export default function DocItemMetadata(): JSX.Element { | ||
const {metadata, frontMatter, assets} = useDoc(); | ||
return ( | ||
<PageMetadata | ||
title={metadata.title} | ||
description={metadata.description} | ||
keywords={frontMatter.keywords} | ||
image={assets.image ?? frontMatter.image} | ||
/> | ||
); | ||
} |
19 changes: 19 additions & 0 deletions
19
packages/docusaurus-theme-classic/src/theme/DocItem/Paginator/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
import React from 'react'; | ||
import {useDoc} from '@docusaurus/theme-common'; | ||
import DocPaginator from '@theme/DocPaginator'; | ||
|
||
/** | ||
* This extra component is needed, because <DocPaginator> should remain generic. | ||
* DocPaginator is used in non-docs contexts too: generated-index pages... | ||
*/ | ||
export default function DocItemPaginator(): JSX.Element { | ||
const {metadata} = useDoc(); | ||
return <DocPaginator previous={metadata.previous} next={metadata.next} />; | ||
} |
23 changes: 23 additions & 0 deletions
23
packages/docusaurus-theme-classic/src/theme/DocItem/TOC/Desktop/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
import React from 'react'; | ||
import {ThemeClassNames, useDoc} from '@docusaurus/theme-common'; | ||
|
||
import TOC from '@theme/TOC'; | ||
|
||
export default function DocItemTOCDesktop(): JSX.Element { | ||
const {toc, frontMatter} = useDoc(); | ||
return ( | ||
<TOC | ||
toc={toc} | ||
minHeadingLevel={frontMatter.toc_min_heading_level} | ||
maxHeadingLevel={frontMatter.toc_max_heading_level} | ||
className={ThemeClassNames.docs.docTocDesktop} | ||
/> | ||
); | ||
} |
25 changes: 25 additions & 0 deletions
25
packages/docusaurus-theme-classic/src/theme/DocItem/TOC/Mobile/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
/** | ||
* Copyright (c) Facebook, Inc. and its affiliates. | ||
* | ||
* This source code is licensed under the MIT license found in the | ||
* LICENSE file in the root directory of this source tree. | ||
*/ | ||
|
||
import React from 'react'; | ||
import clsx from 'clsx'; | ||
import {ThemeClassNames, useDoc} from '@docusaurus/theme-common'; | ||
import TOCCollapsible from '@theme/TOCCollapsible'; | ||
|
||
import styles from './styles.module.css'; | ||
|
||
export default function DocItemTOCMobile(): JSX.Element { | ||
const {toc, frontMatter} = useDoc(); | ||
return ( | ||
<TOCCollapsible | ||
toc={toc} | ||
minHeadingLevel={frontMatter.toc_min_heading_level} | ||
maxHeadingLevel={frontMatter.toc_max_heading_level} | ||
className={clsx(ThemeClassNames.docs.docTocMobile, styles.tocMobile)} | ||
/> | ||
); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.