From fd411371c757c4ff35f2ce8493d956eb4f645a67 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 24 Oct 2022 12:17:15 +0300 Subject: [PATCH] docs: redesigned notes (#2491) --- www/docs/src/css/_code.css | 4 + www/docs/src/css/_note.css | 23 +++ www/docs/src/css/_variables.css | 17 ++ www/docs/src/css/custom.css | 1 + www/docs/src/theme/Admonition/index.js | 157 ++++++++++++++++++ .../src/theme/Admonition/styles.module.css | 31 ++++ www/docs/static/img/info.svg | 6 +- www/docs/static/img/tip.svg | 3 + www/docs/static/img/warning.svg | 3 + 9 files changed, 241 insertions(+), 4 deletions(-) create mode 100644 www/docs/src/css/_note.css create mode 100644 www/docs/src/theme/Admonition/index.js create mode 100644 www/docs/src/theme/Admonition/styles.module.css create mode 100644 www/docs/static/img/tip.svg create mode 100644 www/docs/static/img/warning.svg diff --git a/www/docs/src/css/_code.css b/www/docs/src/css/_code.css index 35fbcf642d779..e3d98336fd0eb 100644 --- a/www/docs/src/css/_code.css +++ b/www/docs/src/css/_code.css @@ -2,6 +2,10 @@ background-color: var(--ifm-code-background); } +code { + border: 1px solid var(--ifm-code-border-color); +} + .docusaurus-highlight-code-line { background-color: rgba(0, 0, 0, 0.1); display: block; diff --git a/www/docs/src/css/_note.css b/www/docs/src/css/_note.css new file mode 100644 index 0000000000000..16fe9e3d7c5e6 --- /dev/null +++ b/www/docs/src/css/_note.css @@ -0,0 +1,23 @@ +.alert { + padding: 16px; + border: 1px solid var(--ifm-note-border-color) !important; + background-color: var(--ifm-note-background); + border-radius: 8px; + box-shadow: none; +} + +.alert p > code { + padding-left: 8px; + padding-right: 8px; + font-size: 14px !important; +} + +html:not([data-theme="dark"]) [class*=alert--] p > code { + --ifm-code-background: #F9FAFB; + --ifm-alert-background-color-highlight: #F9FAFB; +} + +[data-theme="dark"] [class*=alert--] p > code { + --ifm-code-background: #222222; + --ifm-alert-background-color-highlight: #222222; +} \ No newline at end of file diff --git a/www/docs/src/css/_variables.css b/www/docs/src/css/_variables.css index dd9281797132a..3e6f352a8c9ee 100644 --- a/www/docs/src/css/_variables.css +++ b/www/docs/src/css/_variables.css @@ -58,6 +58,15 @@ /* Screen Width */ --ifm-container-width-xl: 960px; + + /* Notes */ + --ifm-note-background: #F9FAFB; + --ifm-note-border-color: #E5E7EB; + --ifm-note-text-color: #4B5563; + + /* Code */ + --ifm-code-border-radius: 8px; + --ifm-code-border-color: #E5E7EB; } html[data-theme="dark"] { @@ -90,4 +99,12 @@ html[data-theme="dark"] { --mode-button-active-bg: #161616; --mode-button-active-border-color: #393939; --mode-button-active-text-color: #F3F3F3; + + /* Notes */ + --ifm-note-background: #222222; + --ifm-note-border-color: #393939; + --ifm-note-text-color: #8A8A8A; + + /* Code */ + --ifm-code-border-color: #393939; } \ No newline at end of file diff --git a/www/docs/src/css/custom.css b/www/docs/src/css/custom.css index 12305afd495e2..1375c8cfdbb4e 100644 --- a/www/docs/src/css/custom.css +++ b/www/docs/src/css/custom.css @@ -15,6 +15,7 @@ @import url('./_docspage.css'); @import url('./_footer.css'); @import url('./_navbar.css'); +@import url('./_note.css'); @import url('./_redocly.css'); @import url('./_sidebar.css'); @import url('./_toc.css'); diff --git a/www/docs/src/theme/Admonition/index.js b/www/docs/src/theme/Admonition/index.js new file mode 100644 index 0000000000000..e78be8c389493 --- /dev/null +++ b/www/docs/src/theme/Admonition/index.js @@ -0,0 +1,157 @@ +import React from 'react'; +import clsx from 'clsx'; +import {ThemeClassNames} from '@docusaurus/theme-common'; +import Translate from '@docusaurus/Translate'; +import styles from './styles.module.css'; +function NoteIcon() { + return ( + + + + ); +} +function TipIcon() { + return ( + + + + ); +} +function DangerIcon() { + return ( + + + + ); +} +function InfoIcon() { + return NoteIcon(); +} +function CautionIcon() { + return DangerIcon(); +} +// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style +const AdmonitionConfigs = { + note: { + infimaClassName: 'secondary', + iconComponent: NoteIcon, + label: ( + + note + + ), + }, + tip: { + infimaClassName: 'success', + iconComponent: TipIcon, + label: ( + + tip + + ), + }, + danger: { + infimaClassName: 'danger', + iconComponent: DangerIcon, + label: ( + + danger + + ), + }, + info: { + infimaClassName: 'info', + iconComponent: InfoIcon, + label: ( + + info + + ), + }, + caution: { + infimaClassName: 'warning', + iconComponent: CautionIcon, + label: ( + + caution + + ), + }, +}; +// Legacy aliases, undocumented but kept for retro-compatibility +const aliases = { + secondary: 'note', + important: 'info', + success: 'tip', + warning: 'danger', +}; +function getAdmonitionConfig(unsafeType) { + const type = aliases[unsafeType] ?? unsafeType; + const config = AdmonitionConfigs[type]; + if (config) { + return config; + } + console.warn( + `No admonition config found for admonition type "${type}". Using Info as fallback.`, + ); + return AdmonitionConfigs.info; +} +// Workaround because it's difficult in MDX v1 to provide a MDX title as props +// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682 +function extractMDXAdmonitionTitle(children) { + const items = React.Children.toArray(children); + const mdxAdmonitionTitle = items.find( + (item) => + React.isValidElement(item) && + item.props?.mdxType === 'mdxAdmonitionTitle', + ); + const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}; + return { + mdxAdmonitionTitle, + rest, + }; +} +function processAdmonitionProps(props) { + const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children); + return { + ...props, + title: props.title ?? mdxAdmonitionTitle, + children: rest, + }; +} +export default function Admonition(props) { + const {children, type, title, icon: iconProp} = processAdmonitionProps(props); + const typeConfig = getAdmonitionConfig(type); + const titleLabel = title ?? typeConfig.label; + const {iconComponent: IconComponent} = typeConfig; + const icon = iconProp ?? ; + return ( +
+
+ {icon} +
{children}
+
+
+ ); +} diff --git a/www/docs/src/theme/Admonition/styles.module.css b/www/docs/src/theme/Admonition/styles.module.css new file mode 100644 index 0000000000000..a124fb331138f --- /dev/null +++ b/www/docs/src/theme/Admonition/styles.module.css @@ -0,0 +1,31 @@ +.admonition { + margin-bottom: 32px; +} + +.admonitionIcon { + display: inline-block; +} + +.admonitionIcon svg { + display: inline-block; + vertical-align: middle; +} + +.admonitionIcon { + height: 15px; + width: 15px; + margin-right: 16px; +} + +.admonitionContent { + font-size: 14px; + color: var(--ifm-note-text-color); +} + +.admonitionContent > :last-child { + margin-bottom: 0; +} + +.admonitionContentContainer { + display: flex; +} \ No newline at end of file diff --git a/www/docs/static/img/info.svg b/www/docs/static/img/info.svg index 16e435a57071e..25d5282f93d37 100644 --- a/www/docs/static/img/info.svg +++ b/www/docs/static/img/info.svg @@ -1,5 +1,3 @@ - - - - + + diff --git a/www/docs/static/img/tip.svg b/www/docs/static/img/tip.svg new file mode 100644 index 0000000000000..c16aa8e326851 --- /dev/null +++ b/www/docs/static/img/tip.svg @@ -0,0 +1,3 @@ + + + diff --git a/www/docs/static/img/warning.svg b/www/docs/static/img/warning.svg new file mode 100644 index 0000000000000..f0711f8c6608a --- /dev/null +++ b/www/docs/static/img/warning.svg @@ -0,0 +1,3 @@ + + +