deepset-ai · fstau · May 13, 2022 · May 30, 2022 · May 30, 2022
diff --git 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:
+
+* `<!-- meta_title: "CONTENT HERE" -->`
+* `<!-- meta_description: "CONTENT HERE" -->`
+* `<!-- meta_image: "CONTENT HERE" -->`
+
+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
+<!-- meta_title: "Enter HTML title here" -->
+<!-- meta_description: "Enter description here" -->
+<!-- meta_image: "Enter image uri for previews here" -->
+
+# 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
@@ -11,35 +11,33 @@ import { StaticPageProps } from "lib/utils";
 
 type LayoutProps = Pick<
   StaticPageProps,
-  "htmlTitle" | "menu" | "toc" | "editOnGitHubLink" | "stars"
+  "htmlTitle" | "meta" | "menu" | "toc" | "editOnGitHubLink" | "stars"
 >;
 
 const Layout: FC<LayoutProps> = ({
   htmlTitle,
+  meta,
   menu,
   toc,
   editOnGitHubLink,
   stars,
   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 (
     <div className="dark:bg-gray-800">
       <Head>
-        <title>{ htmlTitle ? `Haystack - ${htmlTitle}` : "Haystack Docs" }</title>
+        <title>{ metadata.title }</title>
         <meta name="robots" content="follow, index" />
-        <meta
-          content="Haystack enables Question Answering at Scale"
-          name="description"
-        />
+        <meta content={metadata.description} name="description" />
         <meta
           property="og:url"
           content={`https://haystack.deepset.ai${router.asPath}`}
@@ -49,16 +47,16 @@ const Layout: FC<LayoutProps> = ({
           href={`https://haystack.deepset.ai${router.asPath}`}
         />
         <link rel="icon" href="/img/HaystackIcon.png" />
-        <meta property="og:type" content={meta.type} />
+        <meta property="og:type" content={metadata.type} />
         <meta property="og:site_name" content="Haystack Docs" />
-        <meta property="og:description" content={meta.description} />
-        <meta property="og:title" content={meta.title} />
-        <meta property="og:image" content={meta.image} />
+        <meta property="og:description" content={metadata.description} />
+        <meta property="og:title" content={metadata.title} />
+        <meta property="og:image" content={metadata.image} />
         <meta name="twitter:card" content="summary_large_image" />
         <meta name="twitter:site" content="@deepset_ai" />
-        <meta name="twitter:title" content={meta.title} />
-        <meta name="twitter:description" content={meta.description} />
-        <meta name="twitter:image" content={meta.image} />
+        <meta name="twitter:title" content={metadata.title} />
+        <meta name="twitter:description" content={metadata.description} />
+        <meta name="twitter:image" content={metadata.image} />
       </Head>
       <Header docsType={"haystack"} />
       <DesktopNav menu={menu} />

diff --git a/docs/latest/overview/get_started.mdx b/docs/latest/overview/get_started.mdx
@@ -1,3 +1,6 @@
+<!-- meta_title: "Get Started with Haystack" -->
+<!-- meta_description: "Haystack quick-start guide" -->
+
 # Get Started
 
 <div style={{ marginBottom: "3rem" }} />

diff --git 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(/<!-- meta_title: "(.+)" -->/)
+  const description = md.match(/<!-- meta_description: "(.+)" -->/)
+  const image = md.match(/<!-- meta_image: "(.+)" -->/)
+
+  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
@@ -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<typeof getStaticProps>) {
   return (
     <Layout
@@ -39,6 +41,7 @@ export default function ComponentDoc({
       stars={stars}
       toc={toc}
       htmlTitle={htmlTitle}
+      meta={meta}
     >
       {source && (
         <MDXRemote
@@ -122,12 +125,14 @@ export const getStaticProps: GetStaticProps<StaticPageProps> = 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
@@ -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<typeof getStaticProps>) {
   return (
     <Layout
@@ -39,6 +41,7 @@ export default function GuideDoc({
       stars={stars}
       toc={toc}
       htmlTitle={htmlTitle}
+      meta={meta}
     >
       {source && (
         <MDXRemote
@@ -122,12 +125,14 @@ export const getStaticProps: GetStaticProps<StaticPageProps> = 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
@@ -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<typeof getStaticProps>) {
   return (
     <Layout
@@ -39,6 +41,7 @@ export default function OverviewDoc({
       stars={stars}
       toc={toc}
       htmlTitle={htmlTitle}
+      meta={meta}
     >
       {source && (
         <MDXRemote
@@ -124,12 +127,14 @@ export const getStaticProps: GetStaticProps<StaticPageProps> = 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
@@ -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<typeof getStaticProps>) {
   return (
     <Layout
@@ -39,6 +41,7 @@ export default function PipelineNodeDoc({
       stars={stars}
       toc={toc}
       htmlTitle={htmlTitle}
+      meta={meta}
     >
       {source && (
         <MDXRemote
@@ -122,12 +125,14 @@ export const getStaticProps: GetStaticProps<StaticPageProps> = 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
@@ -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<typeof getStaticProps>) {
   return (
     <Layout
@@ -47,6 +49,7 @@ export default function ReferenceDoc({
       stars={stars}
       toc={toc}
       htmlTitle={htmlTitle}
+      meta={meta}
     >
       <div
         className={styles["nonMdx"]}
@@ -292,12 +295,14 @@ export const getStaticProps: GetStaticProps<StaticPageProps> = 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
@@ -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<typeof getStaticProps>) {
   return (
     <Layout
@@ -46,6 +48,7 @@ export default function TutorialDoc({
       stars={stars}
       toc={toc}
       htmlTitle={htmlTitle}
+      meta={meta}
     >
       <div
         dangerouslySetInnerHTML={{ __html: source as string }}
@@ -291,12 +294,14 @@ export const getStaticProps: GetStaticProps<StaticPageProps> = async ({
     const type = "";
 
     const htmlTitle = getH1FromMarkdown(content);
+    const meta = getMetaFromMarkdown(content);
     const layoutProps = await getStaticLayoutProps({
       content,
       version,
       docTitleSlug,
       type,
       htmlTitle,
+      meta,
     });
 
     return {