Merge pull request #991 from datopian/feature/seo-improvements-ii

SEO Improvements (II) - JSON-LD

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;
+}

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 />}

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!
 

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',

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.
 

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!
 
@@ -38,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" alt="Basic example" />
+<img src="/assets/examples/basic-example.png" alt="Initial state of the PortalJS tutorial project" />
 
 ### Editing the Page
 
@@ -51,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" alt="Editing base example" />
+<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.
 

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.
 

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,14 +27,14 @@ 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.
 
 - `title` that gets displayed as a big header 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" />

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" />

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).
+> For more info on measuring pageviews with Google Analytics see [Google Analytics documentation](https://developers.google.com/analytics/devguides/collection/gtagjs/pages).

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
 

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]]