Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Automatic title and meta description #863

Merged
merged 1 commit into from
Nov 25, 2024
Merged

[docs] Automatic title and meta description #863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/src/app/new/(content)/layout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import * as React from 'react';
import type { Metadata } from 'next/types';
import * as SideNav from 'docs/src/components/SideNav';
import * as QuickNav from 'docs/src/components/quick-nav/QuickNav';
import './layout.css';
Expand Down Expand Up @@ -161,3 +162,8 @@ const nav = [
],
},
];
// Title and description are pulled from <h1> and <Subtitle> in the MDX.
export const metadata: Metadata = {
title: null,
description: null,
};
37 changes: 5 additions & 32 deletions docs/src/components/TableCode.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
import * as React from 'react';
import { Code } from './Code';
import { getChildrenText } from '../getChildrenText';

interface TableCodeProps extends React.ComponentProps<'code'> {
printWidth?: number;
}

/** An inline code component that breaks long union types into multiple lines */
export function TableCode({ children, printWidth = 40, ...props }: TableCodeProps) {
const text = getTextContents(children);
const text = getChildrenText(children);

if (text.includes('|') && text.length > printWidth) {
const unionGroups: React.ReactNode[][] = [];
Expand All @@ -21,17 +22,17 @@ export function TableCode({ children, printWidth = 40, ...props }: TableCodeProp
return;
}

if (getTextContents(child).trim() === '|' && depth < 1) {
if (getChildrenText(child).trim() === '|' && depth < 1) {
groupIndex += 1;
unionGroups.push([]);
return;
}

if (getTextContents(child).trim() === '(') {
if (getChildrenText(child).trim() === '(') {
depth += 1;
}

if (getTextContents(child).trim() === ')') {
if (getChildrenText(child).trim() === ')') {
depth -= 1;
}

Expand All @@ -58,31 +59,3 @@ export function TableCode({ children, printWidth = 40, ...props }: TableCodeProp

return <Code {...props}>{children}</Code>;
}

function getTextContents(node?: React.ReactNode): string {
if (hasChildren(node)) {
return getTextContents(node.props?.children);
}

if (Array.isArray(node)) {
return node.map(getTextContents).flat().filter(Boolean).join('');
}

if (typeof node === 'string') {
return node;
}

return '';
}

function hasChildren(
element?: React.ReactNode,
): element is React.ReactElement<React.PropsWithChildren> {
return (
React.isValidElement(element) &&
typeof element.props === 'object' &&
!!element.props &&
'children' in element.props &&
Boolean(element.props.children)
);
}
29 changes: 29 additions & 0 deletions docs/src/getChildrenText.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
import * as React from 'react';

export function getChildrenText(children?: React.ReactNode): string {
if (hasChildren(children)) {
return getChildrenText(children.props?.children);
}

if (Array.isArray(children)) {
return children.map(getChildrenText).flat().filter(Boolean).join('');
}

if (typeof children === 'string') {
return children;
}

return '';
}

function hasChildren(
element?: React.ReactNode,
): element is React.ReactElement<React.PropsWithChildren> {
return (
React.isValidElement(element) &&
typeof element.props === 'object' &&
!!element.props &&
'children' in element.props &&
Boolean(element.props.children)
);
}
15 changes: 13 additions & 2 deletions docs/src/mdx-components.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,20 @@ import { PropsTable } from './components/reference/PropsTable';
import { AttributesTable } from './components/reference/AttributesTable';
import { CssVariablesTable } from './components/reference/CssVariablesTable';
import { TableCode } from './components/TableCode';
import { getChildrenText } from './getChildrenText';

interface MDXComponents {
[key: string]: React.FC<any> | MDXComponents;
}

export const mdxComponents: MDXComponents = {
code: (props) => <Code className="mx-[0.1em]" {...props} />,
h1: (props) => <h1 className="mb-4 text-3xl font-bold" {...props} />,
h1: (props) => (
<React.Fragment>
<h1 className="mb-4 text-3xl font-bold" {...props} />
<title>{`${getChildrenText(props.children)} · Base UI`}</title>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIR, we wanted to have a richer title than just the title for SEO purposes ("React Dialog component" instead of just "Dialog")

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm I think short titles are a much better experience for the end user.

image

I see MUI docs do that, but I'm not a fan of how messy opening a bunch of tabs from mui.com feels

image

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. It does look better in the browser's tabs.
@oliviertassinari, I remember you were suggesting richer titles in the past. Any opinions on this?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can put the SEO juice in the url

url: /react-component-name
pageTitle: Component name • Base UI

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've agreed on the following for titles and URLs:

Dialog • Base UI
https://base-ui.com/react/dialog

Bonus, URLs are going to match import paths:

// When we do kebab-casing
import { Dialog } from "@base-ui-components/react/dialog"

// Eventually
import { Dialog } from "@base-ui/react/dialog"

Copy link
Member

@oliviertassinari oliviertassinari Nov 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I remember you were suggesting richer titles in the past. Any opinions on this?

@michaldudak Right, so why do the pages of MUI follow those patterns?

  • On the SEO side, if we can trust Moz.com (account), it's a ranking factor. Because
SCR-20241127-neia

Source: https://analytics.moz.com/pro/analytics/analyze-keyword/15825137/2871441/9c418058312a1f68ac62edaa1217a2bc

Personally, I work with a small screen, my tabs are very quickly cut, I can't read them most of the time, I have learned to live without tab titles, so that's why I didn't bother so much. Or maybe it was because I always felt that onboarding is critical considering the duration developers stick to a specific stack. If someone helps win more new % users, and it's not annoying enough for them to leave, then it helps win in the long term?

We can wait to see how those pages rank. I will be curious to see. I'm creating an issue with this idea: mui/mui-public#251.

</React.Fragment>
),
h2: (props) => (
<div className="mt-10 mb-5">
<h2 className="mb-4 scroll-mt-6 text-xl font-medium" {...props} />
Expand Down Expand Up @@ -58,7 +64,12 @@ export const mdxComponents: MDXComponents = {
AttributesTable: (props) => <AttributesTable className="mt-5 mb-6" {...props} />,
CssVariablesTable: (props) => <CssVariablesTable className="mt-5 mb-6" {...props} />,
PropsTable: (props) => <PropsTable className="mt-5 mb-6" {...props} />,
Subtitle: (props) => <p className="-mt-2 mb-5 text-lg text-gray" {...props} />,
Subtitle: (props) => (
<React.Fragment>
<p className="-mt-2 mb-5 text-lg text-gray" {...props} />
<meta name="description" content={getChildrenText(props.children)} />
</React.Fragment>
),
};

export const inlineMdxComponents: MDXComponents = {
Expand Down