From d1981300382fc96c18f7691d12210d907911f489 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Demenech?= <joaommdemenech@gmail.com>
Date: Thu, 20 Jul 2023 18:00:00 -0300
Subject: [PATCH 1/3] [site,seo][s]: add description metadata to main pages

---
 site/components/Layout.tsx   |  4 +++-
 site/content/config.js       |  2 +-
 site/content/docs/index.md   |  9 +++++----
 site/content/guide/index.md  |  1 +
 site/content/howtos/index.md |  1 +
 site/pages/[...slug].tsx     |  1 +
 site/pages/blog.tsx          | 12 ++++++------
 7 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/site/components/Layout.tsx b/site/components/Layout.tsx
index 66496d90..f3fc0b0a 100644
--- a/site/components/Layout.tsx
+++ b/site/components/Layout.tsx
@@ -54,12 +54,14 @@ function useTableOfContents(tableOfContents) {
 export default function Layout({
   children,
   title,
+  description,
   tableOfContents = [],
   isHomePage = false,
   sidebarTree = [],
 }: {
   children;
   title?: string;
+  description?: string;
   tableOfContents?;
   urlPath?: string;
   sidebarTree?: [];
@@ -82,7 +84,7 @@ export default function Layout({
 
   return (
     <>
-      {title && <NextSeo title={title} />}
+      {title && <NextSeo title={title} description={description} />}
       <Nav />
       <div className="mx-auto p-6 bg-background dark:bg-background-dark">
         {isHomePage && <Hero />}
diff --git a/site/content/config.js b/site/content/config.js
index 0265e7b8..c0ce47d3 100644
--- a/site/content/config.js
+++ b/site/content/config.js
@@ -1,7 +1,7 @@
 const config = {
   title: 'PortalJS - The JavaScript framework for data portals.',
   description:
-    'PortalJS is a framework for rapidly building rich data portal frontends using a modern frontend approach.',
+    'PortalJS is a JavaScript framework for rapidly building rich data portal frontends using a modern frontend approach.',
   theme: {
     default: 'dark',
     toggleIcon: '/images/theme-button.svg',
diff --git a/site/content/docs/index.md b/site/content/docs/index.md
index 7a1b9482..b2b08221 100644
--- a/site/content/docs/index.md
+++ b/site/content/docs/index.md
@@ -1,6 +1,7 @@
-<NextSeo title="Getting Started - PortalJS" />
-
-# Getting Started
+---
+title: Getting Started
+description: "Getting started guide and tutorial about data portal-building with PortalJS"
+---
 
 Welcome to the PortalJS documentation!
 
@@ -53,6 +54,6 @@ After refreshing the page, you should see the new text:
 
 <img src="/assets/docs/editing-the-page-1.png" />
 
-Congratulations! The app is up and running and you learned how to edit a page. In the next lesson, you are going to learn how to create new datasets. 
+Congratulations! The app is up and running and you learned how to edit a page. In the next lesson, you are going to learn how to create new datasets.
 
 <DocsPagination next="/docs/creating-new-datasets" />
diff --git a/site/content/guide/index.md b/site/content/guide/index.md
index 6bd11b3f..c41fea64 100644
--- a/site/content/guide/index.md
+++ b/site/content/guide/index.md
@@ -3,6 +3,7 @@ showToc: false
 showSidebar: false
 title: "Markdown-based Websites Guide"
 disableTitle: true
+description: Create markdown-based websites and data portals, update it, add collaborators and discover markdown superpowers with Flowershow and PortalJS
 ---
 
 <Hero title="Markdown-based Websites" subtitle="Create markdown-based website, update it, add collaborators and discover markdown superpowers" />
diff --git a/site/content/howtos/index.md b/site/content/howtos/index.md
index c73760e8..58f3b721 100644
--- a/site/content/howtos/index.md
+++ b/site/content/howtos/index.md
@@ -1,5 +1,6 @@
 ---
 title: Guides and Tutorials
+description: Learn more about how you can achieve different data portal features with PortalJS
 ---
 
 - [[howtos/analytics|How to add web analytics?]]
diff --git a/site/pages/[...slug].tsx b/site/pages/[...slug].tsx
index 8f3d72f0..af639f8b 100644
--- a/site/pages/[...slug].tsx
+++ b/site/pages/[...slug].tsx
@@ -32,6 +32,7 @@ export default function Page({ source, meta, sidebarTree }) {
     <Layout
       tableOfContents={tableOfContents}
       title={meta.title}
+      description={meta.description}
       sidebarTree={sidebarTree}
       urlPath={meta.urlPath}
     >
diff --git a/site/pages/blog.tsx b/site/pages/blog.tsx
index 9a723cba..fee33424 100644
--- a/site/pages/blog.tsx
+++ b/site/pages/blog.tsx
@@ -3,12 +3,15 @@ import computeFields from '@/lib/computeFields';
 import clientPromise from '@/lib/mddb';
 import { BlogsList, SimpleLayout } from '@portaljs/core';
 import * as fs from 'fs';
-import {NextSeo} from 'next-seo';
+import { NextSeo } from 'next-seo';
 
 export default function Blog({ blogs }) {
   return (
     <>
-      <NextSeo title="Blog posts" />
+      <NextSeo
+        title="Blog posts"
+        description="Find news and more information about rapidly building rich data portals using a modern frontend framework in the PortalJS blog"
+      />
       <Layout>
         <SimpleLayout title="Blog posts">
           <BlogsList blogs={blogs} />
@@ -50,12 +53,9 @@ export async function getStaticProps() {
   const blogList = await Promise.all(blogsWithComputedFields);
 
   const blogsSorted = blogList.sort(
-    (a, b) =>
-      new Date(b?.date).getTime() -
-      new Date(a?.date).getTime()
+    (a, b) => new Date(b?.date).getTime() - new Date(a?.date).getTime()
   );
 
-
   return {
     props: {
       blogs: blogsSorted,

From 03c27df800923fba84b23dc6c183c48f1f04693d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Demenech?= <joaommdemenech@gmail.com>
Date: Thu, 20 Jul 2023 18:30:54 -0300
Subject: [PATCH 2/3] [site,seo][s]: alt images, description and titles fixes
 for multiple pages

---
 .../blog/markdowndb-basics-tutorial-2023.md   |   2 +-
 site/content/docs/creating-new-datasets.md    |  16 +-
 site/content/docs/index.md                    |   6 +-
 site/content/docs/searching-datasets.md       |   6 +-
 site/content/docs/showing-metadata.md         |   6 +-
 site/content/howtos/analytics.md              |   7 +-
 site/content/howtos/blog.md                   |   5 +-
 site/content/howtos/comments.md               |   5 +-
 site/content/howtos/drd.md                    | 182 ++++++++----------
 site/content/howtos/markdown.md               |   5 +-
 site/content/howtos/seo.md                    |   7 +-
 site/content/howtos/sitemap.md                |   7 +-
 12 files changed, 122 insertions(+), 132 deletions(-)

diff --git a/site/content/blog/markdowndb-basics-tutorial-2023.md b/site/content/blog/markdowndb-basics-tutorial-2023.md
index f88feddf..3665da10 100644
--- a/site/content/blog/markdowndb-basics-tutorial-2023.md
+++ b/site/content/blog/markdowndb-basics-tutorial-2023.md
@@ -264,7 +264,7 @@ The above script will output the following to the terminal:
 
 ## Done!
 
-That's it! We've just created a simple catalog of our GitHub projects using markdown files and the MarkdownDB package. You can find the full code for this tutorial [here](https://github.com/datopian/markdowndb/tree/main/examples/basic-example).
+That's it! We've just created a simple catalog of our GitHub projects using markdown files and the MarkdownDB package. You can find the [full code for this tutorial here](https://github.com/datopian/markdowndb/tree/main/examples/basic-example).
 
 We look forward to seeing the amazing applications you'll build with this tool!
 
diff --git a/site/content/docs/creating-new-datasets.md b/site/content/docs/creating-new-datasets.md
index 0828771f..e17f3913 100644
--- a/site/content/docs/creating-new-datasets.md
+++ b/site/content/docs/creating-new-datasets.md
@@ -1,6 +1,7 @@
-<NextSeo title="Creating new datasets - PortalJS" />
-
-# Creating new datasets
+---
+title: 'Creating new datasets'
+description: 'PortalJS Tutorial II - Learn how to create new datasets on a data portal'
+---
 
 So far, the PortalJS app we created only has a single page displaying a dataset. Data catalogs and data portals generally showcase many different datasets.
 
@@ -10,7 +11,7 @@ Let's explore how to add and display more datasets to our portal.
 
 As you have seen, in this example a dataset page is just a markdown file on disk plus a data file.
 
-To create a new data showcase page we just create a new markdown file in the `content/` folder and a new data file in the `public/` folder. 
+To create a new data showcase page we just create a new markdown file in the `content/` folder and a new data file in the `public/` folder.
 
 Let's do that now. Create a `content/my-incredible-dataset` folder, and inside this new folder create a `index.md` file with the following content:
 
@@ -19,7 +20,7 @@ Let's do that now. Create a `content/my-incredible-dataset` folder, and inside t
 
 This is my incredible dataset.
 
-## Chart 
+## Chart
 
 <LineChart 
     title="US Population By Decade"  
@@ -42,7 +43,7 @@ Year,Population (mi)
 
 Note that pages are associated with a route based on their pathname, so, to see the new data page, access http://localhost:3000/my-incredible-dataset from the browser. You should see the following:
 
-<img src="/assets/docs/my-incredible-dataset.png" />
+<img src="/assets/docs/my-incredible-dataset.png" alt="Page of a new dataset created on a PortalJS data portal" />
 
 > [!tip]
 > In this tutorial we opted for storing content as markdown files and data as CSV files in the app, but PortalJS can have metadata, data and content stored anywhere.
@@ -58,12 +59,11 @@ List of available datasets:
 
 - [My Awesome Dataset](/my-awesome-dataset)
 - [My Incredible Dataset](/my-incredible-dataset)
-
 ```
 
 From the browser, access http://localhost:3000. You should see the following:
 
-<img src="/assets/docs/datasets-index-page.png" />
+<img src="/assets/docs/datasets-index-page.png" alt="PortalJS data portal with multiple datasets" />
 
 At this point, the app has multiple datasets, and users can find and navigate to any dataset they want. In the next lesson, you are going to learn how to improve this experience with search.
 
diff --git a/site/content/docs/index.md b/site/content/docs/index.md
index b2b08221..da017d91 100644
--- a/site/content/docs/index.md
+++ b/site/content/docs/index.md
@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: "Getting started guide and tutorial about data portal-building with PortalJS"
+description: 'Getting started guide and tutorial about data portal-building with PortalJS'
 ---
 
 Welcome to the PortalJS documentation!
@@ -39,7 +39,7 @@ Let's check it's working and what we have! Open http://localhost:3000 from your
 
 You should see a page like this when you access http://localhost:3000. This is the starter template page which shows the most simple data portal you could have: a simple README plus csv file.
 
-<img src="/assets/examples/basic-example.png" />
+<img src="/assets/examples/basic-example.png" alt="Initial state of the PortalJS tutorial project" />
 
 ### Editing the Page
 
@@ -52,7 +52,7 @@ Let’s try editing the starter page.
 
 After refreshing the page, you should see the new text:
 
-<img src="/assets/docs/editing-the-page-1.png" />
+<img src="/assets/docs/editing-the-page-1.png" alt="PortalJS tutorial project after a simple change is made by a user" />
 
 Congratulations! The app is up and running and you learned how to edit a page. In the next lesson, you are going to learn how to create new datasets.
 
diff --git a/site/content/docs/searching-datasets.md b/site/content/docs/searching-datasets.md
index 874b1d74..a672c558 100644
--- a/site/content/docs/searching-datasets.md
+++ b/site/content/docs/searching-datasets.md
@@ -26,7 +26,7 @@ This example makes use of the [markdowndb](https://github.com/datopian/markdownd
 
 From the browser, access http://localhost:3000. You should see the following, you now have a searchable automatic list of your datasets:
 
-![](https://i.imgur.com/9HfSPIx.png)
+![Simple data catalog built with PortalJS](https://i.imgur.com/9HfSPIx.png)
 
 To make this catalog look even better, we can change the text that is being displayed for each dataset to a title. Let's do that by adding the "title" [frontmatter field](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/) to the first dataset in the list. Change `content/my-awesome-dataset/index.md` to the following:
 
@@ -46,7 +46,7 @@ Built with PortalJS
 
 Rerun `npm run mddb` and, from the browser, access http://localhost:3000. You should see the title appearing instead of the folder name:
 
-![](https://i.imgur.com/nvmSnJ5.png)
+![Example of a newly added dataset on a data catalog built with PortalJS](https://i.imgur.com/nvmSnJ5.png)
 
 Any frontmatter attribute that you add will automatically get indexed and be usable in the search box.
 
@@ -102,7 +102,7 @@ List of available datasets:
 
 You now have a filter in your page with all possible values automatically added to it.
 
-![](https://i.imgur.com/p2miSdg.png)
+![Data catalog with facets built with PortalJS](https://i.imgur.com/p2miSdg.png)
 
 In the next lesson, you are going to learn how to display metadata on the dataset page.
 
diff --git a/site/content/docs/showing-metadata.md b/site/content/docs/showing-metadata.md
index e8ab31e0..9f846af9 100644
--- a/site/content/docs/showing-metadata.md
+++ b/site/content/docs/showing-metadata.md
@@ -4,7 +4,7 @@
 
 If you go now to `http://localhost:3000/my-awesome-dataset`, you will see that we now have two titles on the page. That's because `title` is one of the default metadata fields supported by PortalJS.
 
-![](https://i.imgur.com/O145uuc.png)
+![Example of a page displaying the title metadata twice](https://i.imgur.com/O145uuc.png)
 
 Change the content inside `/content/my-awesome-dataset/index.md` to this.
 
@@ -27,7 +27,7 @@ Built with PortalJS
 
 Once you refresh the page at `http://localhost:3000/my-awesome-dataset` you should see something like this at the top:
 
-![](https://i.imgur.com/nvDYJQT.png)
+![Example of a dataset page displaying metadata](https://i.imgur.com/nvDYJQT.png)
 
 These are the standard metadata fields that will be shown at the top of the page if you add them.
 
@@ -35,6 +35,6 @@ These are the standard metadata fields that will be shown at the top of the page
 - `author`, `description`, and `modified` which gets displayed below the title
 - `files` that get displayed as a table with two columns: `File` which is linked directly to the file, and `Format` which show the file format.
 
-Feel free to experiment with these metadata fields. At this point, you might want to deploy the app, and that's what you are going to learn in the next lesson. 
+Feel free to experiment with these metadata fields. At this point, you might want to deploy the app, and that's what you are going to learn in the next lesson.
 
 <DocsPagination prev="/docs/searching-datasets" next="/docs/deploying-your-portaljs-app" />
diff --git a/site/content/howtos/analytics.md b/site/content/howtos/analytics.md
index 25fb35e1..d2681f64 100644
--- a/site/content/howtos/analytics.md
+++ b/site/content/howtos/analytics.md
@@ -1,4 +1,7 @@
-# How to add Google Analytics?
+---
+title: How to add Google Analytics?
+description: Learn to implement Google Analytics on PortalJS data portals
+---
 
 >[!todo] Prerequisites
 >- [Google Analytics account](https://support.google.com/analytics/answer/9304153?hl=en)
@@ -74,4 +77,4 @@ export default function MyApp({ Component, pageProps }) {
 ```
 
 >[!info]
-> For more info on measuring pageviews with Google Analytics see [Google Analytics documentation](https://developers.google.com/analytics/devguides/collection/gtagjs/pages).
\ No newline at end of file
+> For more info on measuring pageviews with Google Analytics see [Google Analytics documentation](https://developers.google.com/analytics/devguides/collection/gtagjs/pages).
diff --git a/site/content/howtos/blog.md b/site/content/howtos/blog.md
index 701c404a..4b4a83a1 100644
--- a/site/content/howtos/blog.md
+++ b/site/content/howtos/blog.md
@@ -1,4 +1,7 @@
-# How to add a simple blog?
+---
+title: How to add a simple blog?
+description: How to add a simple blog on a PortalJS data portal
+---
 
 ## Setup
 
diff --git a/site/content/howtos/comments.md b/site/content/howtos/comments.md
index 8303f5f9..23f6d115 100644
--- a/site/content/howtos/comments.md
+++ b/site/content/howtos/comments.md
@@ -1,4 +1,7 @@
-# How to add user comments?
+---
+title: How to add user comments?
+description: Learn how to add user comments on a PortalJS data portal
+---
 
 ![[comments-example.png]]
 
diff --git a/site/content/howtos/drd.md b/site/content/howtos/drd.md
index 47295d57..389fe610 100644
--- a/site/content/howtos/drd.md
+++ b/site/content/howtos/drd.md
@@ -1,4 +1,7 @@
-# How to create data-rich documents with charts and tables?
+---
+title: How to create data-rich documents with charts and tables?
+description: Learn how to create a data-rich document with charts and tables on a PortalJS data portal
+---
 
 > [!info] Prerequisites
 > If you want to enrich your markdown content with charts and tables, you first need to add support for rendering markdown files in your PortalJS app. Follow [[markdown|this guide]] to learn how to do this.
@@ -15,12 +18,12 @@ Now, in order to use these components in your markdown files, we need to pass th
 
 ```tsx
 // e.g. /blog/[[...slug]].tsx
-import fs from "fs";
-import { LineChart, Table, Catalog, Vega, VegaLite } from "@portaljs/components";
+import fs from 'fs';
+import { LineChart, Table, Catalog, Vega, VegaLite } from '@portaljs/components';
 
-import { MdxRemote } from "next-mdx-remote";
-import clientPromise from "@/lib/mddb.mjs";
-import parse from "@/lib/markdown";
+import { MdxRemote } from 'next-mdx-remote';
+import clientPromise from '@/lib/mddb.mjs';
+import parse from '@/lib/markdown';
 
 const components = {
   Table: Table,
@@ -29,37 +32,35 @@ const components = {
   LineChart: LineChart,
 };
 
-
 export default function Page({ source }) {
-    source = JSON.parse(source);
+  source = JSON.parse(source);
 
-    return (
-        <>
-            <MdxRemote source={source} components={components} />
-        </>
-    );
+  return (
+    <>
+      <MdxRemote source={source} components={components} />
+    </>
+  );
 }
 
 // Import metadata of a file matching the static path and return its parsed source and frontmatter object
 export const getStaticProps = async ({ params }) => {
-    const urlPath = params?.slug ? (params.slug as string[]).join("/") : "/";
+  const urlPath = params?.slug ? (params.slug as string[]).join('/') : '/';
 
-    const mddb = await clientPromise;
-    const dbFile = await mddb.getFileByUrl(urlPath);
-    const filePath = dbFile!.file_path;
-    // const frontMatter = dbFile!.metadata ?? {};
+  const mddb = await clientPromise;
+  const dbFile = await mddb.getFileByUrl(urlPath);
+  const filePath = dbFile!.file_path;
+  // const frontMatter = dbFile!.metadata ?? {};
 
-    const source = fs.readFileSync(filePath, { encoding: "utf-8" });
-    const { mdxSource } = await parse(source, "mdx", {});
+  const source = fs.readFileSync(filePath, { encoding: 'utf-8' });
+  const { mdxSource } = await parse(source, 'mdx', {});
 
-    return {
-        props: {
-            source: JSON.stringify(mdxSource),
-            // frontMatter
-        },
-    };
+  return {
+    props: {
+      source: JSON.stringify(mdxSource),
+      // frontMatter
+    },
+  };
 };
-
 ```
 
 You can now use these components in your markdown, like so:
@@ -93,39 +94,39 @@ Example usage:
   cols={[
     {
       key: 'id',
-      name: 'ID'
+      name: 'ID',
     },
     {
       key: 'firstName',
-      name: 'First name'
+      name: 'First name',
     },
     {
       key: 'lastName',
-      name: 'Last name'
+      name: 'Last name',
     },
     {
       key: 'age',
-      name: 'Age'
-    }
+      name: 'Age',
+    },
   ]}
   data={[
     {
       age: 35,
       firstName: 'Jon',
       id: 1,
-      lastName: 'Snow'
+      lastName: 'Snow',
     },
     {
       age: 42,
       firstName: 'Cersei',
       id: 2,
-      lastName: 'Lannister'
-    }
+      lastName: 'Lannister',
+    },
   ]}
 />
 ```
 
->[!info]
+> [!info]
 > More info on the [storybook page](https://storybook.portaljs.org/?path=/docs/components-table--docs)
 
 ### Linechart
@@ -139,31 +140,16 @@ Example usage:
 ```js
 <LineChart
   data={[
-    [
-      '1850',
-      -0.41765878
-    ],
-    [
-      '1851',
-      -0.2333498
-    ],
-    [
-      '1852',
-      -0.22939907
-    ],
-    [
-      '1853',
-      -0.27035445
-    ],
-    [
-      '1854',
-      -0.29163003
-    ]
+    ['1850', -0.41765878],
+    ['1851', -0.2333498],
+    ['1852', -0.22939907],
+    ['1853', -0.27035445],
+    ['1854', -0.29163003],
   ]}
- />
+/>
 ```
 
->[!info]
+> [!info]
 > More info on the [storybook page](https://storybook.portaljs.org/?path=/docs/components-linechart--docs)
 
 ### Vega chart
@@ -179,30 +165,30 @@ Example usage:
     table: [
       {
         x: 1850,
-        y: -0.418
+        y: -0.418,
       },
       {
         x: 2020,
-        y: 0.923
-      }
-    ]
+        y: 0.923,
+      },
+    ],
   }}
   spec={{
     $schema: 'https://vega.github.io/schema/vega-lite/v4.json',
     data: {
-      name: 'table'
+      name: 'table',
     },
     encoding: {
       x: {
         field: 'x',
-        type: 'ordinal'
+        type: 'ordinal',
       },
       y: {
         field: 'y',
-        type: 'quantitative'
-      }
+        type: 'quantitative',
+      },
     },
-    mark: 'bar'
+    mark: 'bar',
   }}
 />
 ```
@@ -222,35 +208,35 @@ Example usage:
     table: [
       {
         x: 1850,
-        y: -0.418
+        y: -0.418,
       },
       {
         x: 2020,
-        y: 0.923
-      }
-    ]
+        y: 0.923,
+      },
+    ],
   }}
   spec={{
     $schema: 'https://vega.github.io/schema/vega-lite/v4.json',
     data: {
-      name: 'table'
+      name: 'table',
     },
     encoding: {
       x: {
         field: 'x',
-        type: 'ordinal'
+        type: 'ordinal',
       },
       y: {
         field: 'y',
-        type: 'quantitative'
-      }
+        type: 'quantitative',
+      },
     },
-    mark: 'bar'
+    mark: 'bar',
   }}
 />
 ```
 
->[!info]
+> [!info]
 > More info on the [storybook page](https://storybook.portaljs.org/?path=/docs/components-vegalite--docs)
 
 ### Catalog
@@ -269,28 +255,21 @@ Example usage:
       metadata: {
         'details-of-task': 'Detect and categorise abusive language in social media data',
         language: 'Albanian',
-        'level-of-annotation': [
-          'Posts'
-        ],
+        'level-of-annotation': ['Posts'],
         'link-to-data': 'https://doi.org/10.6084/m9.figshare.19333298.v1',
         'link-to-publication': 'https://arxiv.org/abs/2107.13592',
-        medium: [
-          'Text'
-        ],
+        medium: ['Text'],
         'percentage-abusive': 13.2,
-        platform: [
-          'Instagram',
-          'Youtube'
-        ],
+        platform: ['Instagram', 'Youtube'],
         reference: 'Nurce, E., Keci, J., Derczynski, L., 2021. Detecting Abusive Albanian. arXiv:2107.13592',
         'size-of-dataset': 11874,
         'task-description': 'Hierarchical (offensive/not; untargeted/targeted; person/group/other)',
-        title: 'Detecting Abusive Albanian'
+        title: 'Detecting Abusive Albanian',
       },
-      url_path: 'dataset-4'
+      url_path: 'dataset-4',
     },
   ]}
- />
+/>
 ```
 
 You can also add facets that are going to act as filters for your metadata.
@@ -305,30 +284,23 @@ You can also add facets that are going to act as filters for your metadata.
       metadata: {
         'details-of-task': 'Detect and categorise abusive language in social media data',
         language: 'Albanian',
-        'level-of-annotation': [
-          'Posts'
-        ],
+        'level-of-annotation': ['Posts'],
         'link-to-data': 'https://doi.org/10.6084/m9.figshare.19333298.v1',
         'link-to-publication': 'https://arxiv.org/abs/2107.13592',
-        medium: [
-          'Text'
-        ],
+        medium: ['Text'],
         'percentage-abusive': 13.2,
-        platform: [
-          'Instagram',
-          'Youtube'
-        ],
+        platform: ['Instagram', 'Youtube'],
         reference: 'Nurce, E., Keci, J., Derczynski, L., 2021. Detecting Abusive Albanian. arXiv:2107.13592',
         'size-of-dataset': 11874,
         'task-description': 'Hierarchical (offensive/not; untargeted/targeted; person/group/other)',
-        title: 'Detecting Abusive Albanian'
+        title: 'Detecting Abusive Albanian',
       },
-      url_path: 'dataset-4'
+      url_path: 'dataset-4',
     },
   ]}
   facets={['platform', 'language']}
- />
+/>
 ```
-  
->[!info]
+
+> [!info]
 > More info on the [storybook page](https://storybook.portaljs.org/?path=/docs/components-catalog--docs)
diff --git a/site/content/howtos/markdown.md b/site/content/howtos/markdown.md
index ea295f71..b358f81e 100644
--- a/site/content/howtos/markdown.md
+++ b/site/content/howtos/markdown.md
@@ -1,4 +1,7 @@
-# How to add markdown-based content pages?
+---
+title: How to add markdown-based content pages?
+description: Learn how to add markdown-based content pages on PortalJS data portals
+---
 
 ## Add content layer to your app
 
diff --git a/site/content/howtos/seo.md b/site/content/howtos/seo.md
index 42d3c544..cc272160 100644
--- a/site/content/howtos/seo.md
+++ b/site/content/howtos/seo.md
@@ -1,4 +1,7 @@
-# How to customize page metadata for SEO?
+---
+title: How to customize page metadata for SEO?
+description: Learn to customize page metadata for SEO on data portals with PortalJS
+---
 
 >[!info]
 >See [`next-seo` documentation](https://github.com/garmeeh/next-seo) to learn more.
@@ -76,4 +79,4 @@ export default function Page() (
 ```
 
 >[!info]
-> To learn more on per-page SEO configuration with `next-seo`, see [this docs section](https://github.com/garmeeh/next-seo#add-seo-to-page)
\ No newline at end of file
+> To learn more on per-page SEO configuration with `next-seo`, see [this docs section](https://github.com/garmeeh/next-seo#add-seo-to-page)
diff --git a/site/content/howtos/sitemap.md b/site/content/howtos/sitemap.md
index 1f63daa5..c552e78b 100644
--- a/site/content/howtos/sitemap.md
+++ b/site/content/howtos/sitemap.md
@@ -1,4 +1,7 @@
-# How to build a sitemap?
+---
+title: How to build a sitemap?
+description: Learn how to build a sitemap for a data portal with PortalJS
+---
 
 ## Setup
 
@@ -91,4 +94,4 @@ Add this to the scripts section in your `package.json` to regenerate the sitemap
 
 "prebuild": "node ./scripts/sitemap.mjs",
 
-```
\ No newline at end of file
+```

From d367deaea34acca38cc28c705085f21286b5bf7e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Demenech?= <joaommdemenech@gmail.com>
Date: Wed, 26 Jul 2023 18:00:12 -0300
Subject: [PATCH 3/3] [seo,json-ld][m]: implement json-ld (schema markups)

---
 site/components/JSONLD.tsx | 65 ++++++++++++++++++++++++++++++++++++++
 site/content/docs/index.md |  5 ---
 site/pages/[...slug].tsx   | 22 +++++++------
 site/pages/index.tsx       |  5 +++
 4 files changed, 83 insertions(+), 14 deletions(-)
 create mode 100644 site/components/JSONLD.tsx

diff --git a/site/components/JSONLD.tsx b/site/components/JSONLD.tsx
new file mode 100644
index 00000000..b6726597
--- /dev/null
+++ b/site/components/JSONLD.tsx
@@ -0,0 +1,65 @@
+import { ArticleJsonLd } from 'next-seo';
+import { useRouter } from 'next/router';
+
+export default function JSONLD({
+  meta,
+  source,
+}: {
+  meta: any;
+  source: string;
+}): JSX.Element {
+  if (!source) {
+    return <></>;
+  }
+
+  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://portaljs.org';
+  const pageUrl = `${baseUrl}/${meta.urlPath}`;
+
+  const imageMatches = source.match(
+    /(?<=src: ")(.*)\.((png)|(jpg)|(jpeg))(?=")/g
+  );
+  let images = [];
+  if (imageMatches) {
+    images = [...imageMatches];
+    images = images.map((img) =>
+      img.startsWith('http')
+        ? img
+        : `${baseUrl}${img.startsWith('/') ? '' : '/'}${img}`
+    );
+  }
+
+  let Component: JSX.Element;
+
+  const isBlog: boolean =
+    /^blog\/.*/.test(meta.urlPath) || meta.filetype === 'blog';
+  const isDoc: boolean = /^((docs)|(howtos\/)|(guide\/)).*/.test(meta.urlPath);
+
+  if (isBlog) {
+    Component = (
+      <ArticleJsonLd
+        type="BlogPosting"
+        url={pageUrl}
+        title={meta.title}
+        datePublished={meta.date}
+        dateModified={meta.date}
+        authorName={meta.authors.length ? meta.authors[0].name : 'PortalJS'}
+        description={meta.description}
+        images={images}
+      />
+    );
+  } else if (isDoc) {
+    Component = (
+      <ArticleJsonLd
+        url={pageUrl}
+        title={meta.title}
+        images={images}
+        datePublished={meta.date}
+        dateModified={meta.date}
+        authorName={meta.authors.length ? meta.authors[0].name : 'PortalJS'}
+        description={meta.description}
+      />
+    );
+  }
+
+  return Component;
+}
diff --git a/site/content/docs/index.md b/site/content/docs/index.md
index 0982d360..da017d91 100644
--- a/site/content/docs/index.md
+++ b/site/content/docs/index.md
@@ -52,12 +52,7 @@ Let’s try editing the starter page.
 
 After refreshing the page, you should see the new text:
 
-<<<<<<< HEAD
 <img src="/assets/docs/editing-the-page-1.png" alt="PortalJS tutorial project after a simple change is made by a user" />
-=======
-<img src="/assets/docs/editing-the-page-1.png" alt="Editing base example" />
-
-> > > > > > > da226ef2056391bc2f710b6229645c25488485fb
 
 Congratulations! The app is up and running and you learned how to edit a page. In the next lesson, you are going to learn how to create new datasets.
 
diff --git a/site/pages/[...slug].tsx b/site/pages/[...slug].tsx
index af639f8b..3a61a008 100644
--- a/site/pages/[...slug].tsx
+++ b/site/pages/[...slug].tsx
@@ -12,6 +12,7 @@ import { GetStaticProps, GetStaticPropsResult } from 'next';
 import { CustomAppProps } from './_app.jsx';
 import computeFields from '@/lib/computeFields';
 import { getAuthorsDetails } from '@/lib/getAuthorsDetails';
+import JSONLD from '@/components/JSONLD';
 
 export default function Page({ source, meta, sidebarTree }) {
   source = JSON.parse(source);
@@ -29,15 +30,18 @@ export default function Page({ source, meta, sidebarTree }) {
   }, [router.asPath]); // update table of contents on route change with next/link
 
   return (
-    <Layout
-      tableOfContents={tableOfContents}
-      title={meta.title}
-      description={meta.description}
-      sidebarTree={sidebarTree}
-      urlPath={meta.urlPath}
-    >
-      <MDXPage source={source} frontMatter={meta} />
-    </Layout>
+    <>
+      <JSONLD meta={meta} source={source.compiledSource} />
+      <Layout
+        tableOfContents={tableOfContents}
+        title={meta.title}
+        description={meta.description}
+        sidebarTree={sidebarTree}
+        urlPath={meta.urlPath}
+      >
+        <MDXPage source={source} frontMatter={meta} />
+      </Layout>
+    </>
   );
 }
 
diff --git a/site/pages/index.tsx b/site/pages/index.tsx
index 275bc8e1..1222c57a 100644
--- a/site/pages/index.tsx
+++ b/site/pages/index.tsx
@@ -8,6 +8,7 @@ import { useRouter } from 'next/router';
 import { useEffect, useState } from 'react';
 import { collectHeadings } from '@portaljs/core';
 import Head from 'next/head';
+import { LogoJsonLd } from 'next-seo';
 
 export default function Home({ sidebarTree }) {
   const router = useRouter();
@@ -24,6 +25,10 @@ export default function Home({ sidebarTree }) {
 
   return (
     <>
+      <LogoJsonLd
+        url="https://portaljs.org"
+        logo="https://portaljs.org/icon.png"
+      />
       <Layout
         isHomePage={true}
         tableOfContents={tableOfContents}