diff --git a/README.md b/README.md index f248a2ecb..9af0aeb3d 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,28 @@ After releasing the docs, we need to release the benchmarks. Create a new versio If you now start the local sever and go to the new version, you will see the 404 page. We pull the version from the haystack release tags. Most likely, the newest version is not released yet. Therefore, you have to add it manually to the array `tagNames` in the function `getDocsVersions` by adding the command `tagNames.push('v0.10.0');`. +### Document Metadata + +You can overwrite the default meta tags (title, description, image, etc.) for individual pages, by adding HTML comments in the source files. The page currently support title, description and image. +The properties must be provided exactly in the format specified below: + +* `` +* `` +* `` + +Properties that have not been provided or weren't parsed correctly will be overwritten by their default. For the title this is the content of the first H1 in the document prefixed with "Haystack - ". + +#### Example + +```md + + + + +# Document Starts +... +``` + ## Styling We use [Tailwind](https://tailwindcss.com) for CSS. It's a CSS utility library, which allows us to write barely any CSS ourselves. The `tailwind.config.js` file contains configuration to provide classes that match deepset.ai's new style guide. Additionally, there is a `styles/global.css` file, which loads our custom font provided by the style guide. Lastly, we have two css module files within the `components` directory (markdown.module.css and tutorial.module.css), wich are applied on the `components/Layout` component. These files allow us to provide some defaults for certain HTML elements, which get applied to the HTML tags generated when we convert markdown to html at build time. We also use a React component library authored by the Tailwind team, called [Headless UI](http://headlessui.dev/). This allows us to easily create React components such as the `components/Tabs` and `components/Disclosures` components. diff --git a/components/Layout.tsx b/components/Layout.tsx index 57d1397db..365d7b250 100644 --- a/components/Layout.tsx +++ b/components/Layout.tsx @@ -11,11 +11,12 @@ import { StaticPageProps } from "lib/utils"; type LayoutProps = Pick< StaticPageProps, - "htmlTitle" | "menu" | "toc" | "editOnGitHubLink" | "stars" + "htmlTitle" | "meta" | "menu" | "toc" | "editOnGitHubLink" | "stars" >; const Layout: FC = ({ htmlTitle, + meta, menu, toc, editOnGitHubLink, @@ -23,23 +24,20 @@ const Layout: FC = ({ children, }) => { const router = useRouter(); - - const meta = { - title: "Haystack Docs", - description: "Haystack enables Question Answering at Scale", - image: "/img/haystack-logo-colored.png", - type: "website", - }; + + const metadata = { + title: meta?.title ? meta.title : (htmlTitle ? `Haystack - ${htmlTitle}` : "Haystack Docs"), + description: meta?.description || "Haystack enables Question Answering at Scale", + image: meta?.image || "/img/haystack-logo-colored.png", + type: meta?.type || "website", + } return (
- { htmlTitle ? `Haystack - ${htmlTitle}` : "Haystack Docs" } + { metadata.title } - + = ({ href={`https://haystack.deepset.ai${router.asPath}`} /> - + - - - + + + - - - + + +
diff --git a/docs/latest/overview/get_started.mdx b/docs/latest/overview/get_started.mdx index e0c1d61fa..e62b0d8b0 100644 --- a/docs/latest/overview/get_started.mdx +++ b/docs/latest/overview/get_started.mdx @@ -1,3 +1,6 @@ + + + # Get Started
diff --git a/lib/utils.ts b/lib/utils.ts index 9957de601..8fbcaca35 100644 --- a/lib/utils.ts +++ b/lib/utils.ts @@ -48,6 +48,7 @@ export const markdownToHtml = async ({ export type StaticPageProps = { htmlTitle?: string; + meta?: Metadata; menu: any; toc: { text: string; level: number; link: string }[]; editOnGitHubLink: string; @@ -61,12 +62,14 @@ export const getStaticLayoutProps = async ({ docTitleSlug, type, htmlTitle, + meta, }: { content: string; version?: string; docTitleSlug: string; type: string; htmlTitle?: string; + meta?: Metadata; }) => { const getHeadings = () => { const headingLines = content @@ -93,7 +96,7 @@ export const getStaticLayoutProps = async ({ stars = await getStargazersCount(); } - return { menu, toc, editOnGitHubLink, stars, htmlTitle }; + return { menu, toc, editOnGitHubLink, stars, htmlTitle, meta }; }; export const getMenu = async (version?: string) => { @@ -164,3 +167,23 @@ export const getH1FromMarkdown = (md: string): string => { if (matches?.length != 1) return ""; return matches[0].slice(2); }; + +export interface Metadata { + title: string; + description: string; + image: string; + type: string; +} + +export const getMetaFromMarkdown = (md: string): Metadata => { + const title = md.match(//) + const description = md.match(//) + const image = md.match(//) + + return { + title: title?.at(1) || "", + description: description?.at(1) || "", + image: image?.at(1) || "", + type: "website", + } +} diff --git a/pages/components/[...slug].tsx b/pages/components/[...slug].tsx index ba8a7c8ad..4c05a6935 100644 --- a/pages/components/[...slug].tsx +++ b/pages/components/[...slug].tsx @@ -21,6 +21,7 @@ import { getStaticLayoutProps, StaticPageProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { components } from "lib/mdx"; @@ -31,6 +32,7 @@ export default function ComponentDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return ( {source && ( = async ({ const type = "components"; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, htmlTitle, + meta, }); return { diff --git a/pages/guides/[...slug].tsx b/pages/guides/[...slug].tsx index cb4a15024..c3b93de38 100644 --- a/pages/guides/[...slug].tsx +++ b/pages/guides/[...slug].tsx @@ -21,6 +21,7 @@ import { getStaticLayoutProps, StaticPageProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { components } from "lib/mdx"; @@ -31,6 +32,7 @@ export default function GuideDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return ( {source && ( = async ({ const type = "guides"; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, htmlTitle, + meta, }); return { diff --git a/pages/overview/[...slug].tsx b/pages/overview/[...slug].tsx index 1ff1df90d..84d43ae04 100644 --- a/pages/overview/[...slug].tsx +++ b/pages/overview/[...slug].tsx @@ -21,6 +21,7 @@ import { StaticPageProps, getStaticLayoutProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { components } from "lib/mdx"; @@ -31,6 +32,7 @@ export default function OverviewDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return ( {source && ( = async ({ const type = "overview"; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, - htmlTitle + htmlTitle, + meta, }); return { diff --git a/pages/pipeline_nodes/[...slug].tsx b/pages/pipeline_nodes/[...slug].tsx index ed4873c0b..4bebd0869 100644 --- a/pages/pipeline_nodes/[...slug].tsx +++ b/pages/pipeline_nodes/[...slug].tsx @@ -21,6 +21,7 @@ import { getStaticLayoutProps, StaticPageProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { components } from "lib/mdx"; @@ -31,6 +32,7 @@ export default function PipelineNodeDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return ( {source && ( = async ({ const type = "pipeline_nodes"; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, htmlTitle, + meta, }); return { diff --git a/pages/reference/[...slug].tsx b/pages/reference/[...slug].tsx index c0b089ab7..20e9ae877 100644 --- a/pages/reference/[...slug].tsx +++ b/pages/reference/[...slug].tsx @@ -14,6 +14,7 @@ import { getStaticLayoutProps, StaticPageProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { referenceFilesLatest } from "lib/constants"; import { referenceFilesV140 } from "lib/constants"; @@ -39,6 +40,7 @@ export default function ReferenceDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return (
= async ({ const type = ""; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, htmlTitle, + meta, }); return { diff --git a/pages/tutorials/[...slug].tsx b/pages/tutorials/[...slug].tsx index 4b291217f..640f2311b 100644 --- a/pages/tutorials/[...slug].tsx +++ b/pages/tutorials/[...slug].tsx @@ -14,6 +14,7 @@ import { getStaticLayoutProps, StaticPageProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { tutorialFilesLatest } from "lib/constants"; import { tutorialFilesV140 } from "lib/constants"; @@ -38,6 +39,7 @@ export default function TutorialDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return (
= async ({ const type = ""; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, htmlTitle, + meta, }); return { diff --git a/pages/usage/[...slug].tsx b/pages/usage/[...slug].tsx index cfc5c8e53..222e48ca9 100644 --- a/pages/usage/[...slug].tsx +++ b/pages/usage/[...slug].tsx @@ -21,6 +21,7 @@ import { getStaticLayoutProps, StaticPageProps, getH1FromMarkdown, + getMetaFromMarkdown, } from "lib/utils"; import { components } from "lib/mdx"; @@ -31,6 +32,7 @@ export default function UsageDoc({ stars, source, htmlTitle, + meta, }: InferGetStaticPropsType) { return ( {source && ( = async ({ const type = "usage"; const htmlTitle = getH1FromMarkdown(content); + const meta = getMetaFromMarkdown(content); const layoutProps = await getStaticLayoutProps({ content, version, docTitleSlug, type, - htmlTitle + htmlTitle, + meta }); return {