DEV Community: Cesar Varela

Improve your SEO by adding a sitemap to your Gatsby MDX blog

Cesar Varela — Thu, 02 Sep 2021 00:41:35 +0000

Our blog is getting better and better. Now it's time to add a sitemap.

Strictly speaking, it is not clear if a sitemap is required since Google's page rank algorithm is a black box. BUT Google recommends adding one so let's do it:

Adding `gatsby-plugin-sitemap`

First, we need to add the official Gatsby sitemap plugin:

npm i gatsby-plugin-sitemap

yarn add gatsby-plugin-sitemap

Next, as always, we have to add the newly installed plugin to our config file:

...
{
      resolve: `gatsby-plugin-sitemap`,
      options: {      
      },
...

This will get the plugin loaded, but we need to specify its options because the defaults will do more harm than good otherwise.

1. Set the `query` option:

...
  query: `
        {
          site {
            siteMetadata {
              url
            }
          }
          allMdx(sort: {fields: frontmatter___date, order: DESC}, filter: {slug: {glob: "!*wip*"}}) {
            nodes {
              frontmatter {
                date(formatString: "YYYY-MM-DD")
              }
              slug
            }
          }
        }
      `,
...

This option lets us get a list of all the pages we'll want to add to our site. We can add more entries manually too, which I'll do next.

2. Set the `resolveSiteUrl`

...
        resolveSiteUrl: ({ site: { siteMetadata: { url } } }) => url,
...

The plugin uses this setting to set an absolute URL in the sitemap, and as you can see, it references the GraphQL result from the previous query setting.

3. Set the `resolvePages` option

        resolvePages: ({ allMdx: { nodes: mdxs } }) => {

          const posts = mdxs.map(mdx => {
            return {
              path: `/blog/${mdx.slug}`,
              lastmod: mdx.frontmatter.date,
              changefreq: 'weekly',
              priority: 0.7,
            }
          })

    // I manually add home and blog entries here

          const home = {
            path: '/',
            lastmod: posts[0].lastmod,
            changefreq: 'daily',
            priority: 0.3,
          }
          const blog = {
            path: '/blog',
            lastmod: posts[0].lastmod,
            changefreq: 'daily',
            priority: 0.3,
          }
          return [...posts, home, blog]
        },

We build an array of entries that will form the sitemap.xml file. Because posts are added constantly, I'm making a list dynamically from the results of the previous GraphQL query. And then, because the Homepage and the Blog index page do not change their attributes often, I manually add them to the list of entries.'

4. Set the serialize option

...
        serialize: ({ path, lastmod, changefreq, priority }) => {
          return {
            url: path,
            lastmod,
            changefreq,
            priority,
          }
        },
...

Finally, we need to map the array we built in the resolvePages option to the sitemap entries themselves. This will be only a passthrough of properties most of the time because resolvePages does most of the work.

For your copy/pasting pleasure, the final code looks like this:

 {
      resolve: `gatsby-plugin-sitemap`,
      options: {
        query: `
        {
          site {
            siteMetadata {
              url
            }
          }
          allMdx(sort: {fields: frontmatter___date, order: DESC}, filter: {slug: {glob: "!*wip*"}}) {
            nodes {
              frontmatter {
                date(formatString: "YYYY-MM-DD")
              }
              slug
            }
          }
        }
      `,
        resolveSiteUrl: ({ site: { siteMetadata: { url } } }) => url,
        resolvePages: ({ allMdx: { nodes: mdxs } }) => {

          const posts = mdxs.map(mdx => {
            return {
              path: `/blog/${mdx.slug}`,
              lastmod: mdx.frontmatter.date,
              changefreq: 'weekly',
              priority: 0.7,
            }
          })

          const home = {
            path: '/',
            lastmod: posts[0].lastmod,
            changefreq: 'daily',
            priority: 0.3,
          }

          const blog = {
            path: '/blog',
            lastmod: posts[0].lastmod,
            changefreq: 'daily',
            priority: 0.3,
          }

          return [...posts, home, blog]
        },
        serialize: ({ path, lastmod, changefreq, priority }) => {
          return {
            url: path,
            lastmod,
            changefreq,
            priority,
          }
        },
      },
    }

5. View your sitemap

If you want to test your newly added sitemap, you have to run gatsby build (because the plugin only gets executed in the build phase) and then gatsby serve, which will run a web server usually at http://localhost:9000.

You can then navigate to localhost:9000/sitemap/sitemap-index.xml and it should look something like this:

<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
<loc>https://cesarvarela.com/sitemap/sitemap-0.xml</loc>
</sitemap>
</sitemapindex>

There you can follow the first link where you will finally see all your blog entries:

...
<url>
<loc>https://cesarvarela.com/blog/add-microdata-to-your-gastby-mdx-blog</loc>
<lastmod>2022-10-08T00:00:00.000Z</lastmod>
<changefreq>weekly</changefreq>
<priority>0.7</priority>
</url>
<url>
<loc>https://cesarvarela.com/blog/fix-source-file-requires-different-compiler-version</loc>
<lastmod>2021-08-18T00:00:00.000Z</lastmod>
<changefreq>weekly</changefreq>
<priority>0.7</priority>
</url>
<url>
<loc>https://cesarvarela.com/blog/how-to-include-javascript-files-in-gatsby</loc>
<lastmod>2021-08-18T00:00:00.000Z</lastmod>
<changefreq>weekly</changefreq>
<priority>0.7</priority>
</url>
...

Bonus: WTF are those Sitemap fields?

If you are new to sitemaps, it will feel a bit cryptic. Let's go over the most relevant options:

url

Must be the canonical URL of the page, in other words, the original source. Avoid having multiple entries on your sitemap pointing to the same page.

lastmod

As you probably guessed, this is the last modified date.
** If you mess up this value, Google will simply ignore it** so be careful, but don't worry much about it either since Google's crawler is smart enough to detect page changes all by itself.

priority

It is a value from 0.0 to 1. Lets you tell Google which pages are more critical relative to other pages on your site.

changefreq

specifies how often the contents of the page change, some possible values are always, hourly, daily, weekly.

*Again, these are hints, Google's crawler will do as it pleases, and you might as well have 1# rank with no sitemap. *

Improve SEO with Microdata on your Gatsby MDX Blog

Cesar Varela — Sun, 22 Aug 2021 07:53:30 +0000

Microdata is an essential part of improving the SEO of your blog, and if you are new to it, it might get a bit confusing. I'll try to make it a bit easier for you to get Microdata working on your blog in this post.

Thankfully, a couple of packages make creating the proper structure of the microdata for our pages more straightforward, especially if you are using typescript:

npm i schema-dts react-schemaorg

yarn add schema-dts react-schemaorg

Next, we have to add a new prop to our <Seo /> component (that comes already created with almost all Gatsby starters) to handle our new Microdata structure. I'll add it in a parameter called script:

...

export default function Seo({ title, script = [] }) {

...

return <Helmet
      title={title}
      titleTemplate={`%s | ${site.siteMetadata.title}`}

      //this is the key line
      script={[].concat(script)}
    />
}

Then when can start adding each microdata structure to our pages and templates. For example, in my post templates, first, I'll import the helmetJsonLdProp helper and the schema type that most reflects a blog post:

import { helmetJsonLdProp } from "react-schemaorg";
import { BlogPosting } from "schema-dts";

It's important to use the helmetJsonLdProp helper because it plays nicely with react-helmet

Then we define the actual Microdata content in the post template render, and send it to our <Seo> component:

const Post = (props) => {

  const { mdx: { body, frontmatter, parent, timeToRead, slug } } = props.data

  const jsonLd = helmetJsonLdProp<BlogPosting>({
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": frontmatter.title,
    "datePublished": frontmatter.date,
    "dateModified": parent.modifiedTime,
    "author": [{
      "@type": "Person",
      "name": "Cesar Varela",
      "url": `https://cesarvarela.com/blog/${slug}`
    }]
  })

  return <Layout content={<LayoutLink to="/blog">Blog</LayoutLink>}>

    // pass the jsonLd data to our Seo component
    <Seo title={frontmatter.title} script={jsonLd} />

    /* my custom post template jsx goes here, yours will vary obsviously  */
 </Layout>

Done! If everything worked nicely, you should see your new Microdata here. And you can read more about it here

Working example here

WTF is Gitmemory?

Cesar Varela — Thu, 19 Aug 2021 07:51:39 +0000

It's just scrapping GitHub issues, and it has appeared a lot on my search results.

Are you guys experiencing the same?

And Gitmemory is not the only site doing this. Others are doing the same. Between this and search results from 2009, I'm thinking of switching to another search engine, especially for development, but I'm not sure there is a better one, though.

How to load images in your MDX blog

Cesar Varela — Tue, 17 Aug 2021 02:10:31 +0000

If you've followed my previous posts about adding a blog to an existing Gatsby site, you'll notice one thing: images don't load.

Thankfully this is pretty easy to fix, so let's do it:

Add a `gatsby-source-filesystem` entry for your images

First, we need to let know Gatsby about the existence of our pictures. I want the images to reside inside the src/blog/images folder and not in src/images (skip this step if you don't care about this).

    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `blog-images`,
        path: `${__dirname}/src/blog/images`,
      },
    },

Add the `gatsby-remark-images` package

yarn add gatsby-remark-images

npm i gatsby-remark-images

And add it to your Gatsby config:

...
    `gatsby-remark-images`,
...

Configure `gatsby-plugin-mdx`

Next, we need to tell gatsby-plugin-mdx to use gatsby-remark-images, and this is done on your Gatsby config too:

{
      resolve: `gatsby-plugin-mdx`,
      options: {
        root: __dirname,
        gatsbyRemarkPlugins: [
          {
            resolve: 'gatsby-remark-images',
            options: {
              maxWidth: 500,
              linkImagesToOriginal: false,
            },
          },
        ],
      },
    },

Use them in your `.mdx` files

Once everything is ready, you should be able to include them like you would with .md files, using a relative path from the current .mdx you are writing on to the image:

...

![smart screen of death](./images/smart-screen.png)

...

You can check an example here

How to Code Sign an Electron App on Windows for cheap, Part 1: Getting the Certificate

Cesar Varela — Sat, 14 Aug 2021 06:14:24 +0000

I'm about to release my first Electron-Based Open Source App (EBOSA?), for which you can read more about it here. And after fighting a bit with electron-forge, I'm reaching the final steps.

Code signing is one of them, and if you are not used to Desktop environments, there is a lot of jargon and confusion waiting for you.

But wait... why codesign in the first place?

I guess you already know this, but if you don't Codesign your App, Windows will treat it as one of the Horsemen of the apocalypse. First, your browser will not allow you to download the .exe, and if you manage to convince it to do so, Windows will show the "You are installing a virus, but we just saved you from doing so" screen:

Chrome:

Windon't:

Too much friction if you want your App to reach as many users as possible, so let's fix it:

1 - Buy a Codesigning Certificate

There are two options, each with its pros and cons:

a - Buy an EV certificate

Pros: EV certificates will make both the browser that Windows happy, and primarily they work right away

Cons: They are more expensive 3x vs. the Individual certificate and slightly harder to get. You'll need a hardware USB key and more steps to get the certificate itself.

b - Buy an Individual certificate (this is what I did)

Pros: They are cheaper, about $85/year (you can buy one here), and it is slightly faster to get and use since you don't need a USB key and the verification process is quicker.

Cons: The browser would let you don't load the .exe without problems, but it will take some installs for the Windows Smart Screen to go away (from what I've read, this varies from App to App, but it is around 100/500 installs)

2 - Assuming you chose option a: generate the certificate

After checking out from the Comodo store, you'll need to start the certificate generation process. They will ask you to fill a few forms and a CSR...

The easiest way I've found to do this was using a tool from DigiCert that you can get here, whit this tool, the CSR generation becomes just a few clicks:

click on Create CSR
select Code Signing
fill the required fields
choose 3072 for the Key Size option
click Generate

Voila! You have a CSR that you can paste in the Comodo certification generation form, and that's it (for now)!

You'll get an email saying that the Comodo team is checking your phone number, and after a couple of days, your certificate should be ready for signing.

How to customize the look of your MDX Gatsby blog

Cesar Varela — Sun, 01 Aug 2021 02:52:55 +0000

This post is the continuation of How to add a blog to your Gatsby site. What we did in the first part works, but it probably won't look the best.

Using MDXProvider

Just rendering the {children} prop that we receive in our layout file works, but if we want to have total control over how the HTML components are rendered and make it easier to use custom ones, we have to use the MDXProvider:

import React from "react"
import { MDXProvider } from "@mdx-js/react"

const PostLayout = ({ children, path }) => {

    return <div>
        <MDXProvider>
            {children}
        </MDXProvider>
    </div>
}

export default PostLayout

Now we have opened the door world of MDX customization:

Customizing how built-in HTML components are rendered, using the components prop

Not sure why would someone want to do this, but you can for example render every h1 as an image or Rick Astley... you get the idea of how powerful this can be:

<MDXProvider components={{ h1: ({ children }) => <img src="rickroll.jpg" />}} >
            {children}
</MDXProvider>

In my case, I want to control how the pre and code elements get rendered. Display a macOS-like window for the pre element (when using triple backticks), and make it a bit more distinguishable from the standard text when using the code tag (when using single backticks).

Adding syntax highlighting to code examples

For this, we need to customize how the pre tags render. We'll use prism-react-renderer that does an excellent job at it.

yarn add prism-react-renderer

npm i prism-react-renderer --save

And then define ourCodeWindow component:

import React from 'react'
import Highlight, { defaultProps } from 'prism-react-renderer'

function CodeWindow({ children }) {
    const { props: { children: source } } = children
    return <div>
        <Highlight {...defaultProps} code={source} language="javascript">
            {({ className, style, tokens, getLineProps, getTokenProps }) => (
                <pre className={className} style={{ ...style, padding: '20px' }}>
                    {tokens.map((line, i) => (
                        <div key={i} {...getLineProps({ line, key: i })}>
                            {line.map((token, key) => (
                                <span key={key} {...getTokenProps({ token, key })} />
                            ))}
                        </div>
                    ))}
                </pre>
            )}
        </Highlight >
    </div>
}

You can read more about how the code inside the Highlight component works here: https://mdxjs.com/guides/syntax-highlighting

depending on the structure of your components, the source code is in a children prop of the children prop that is passed to our CodeWindow component (childrenception)

// source is the actual string inside the triple backticks
 const { props: { children: source } } = children

We can now set this to the components prop of our MDXProvider

const components = {
    pre: props => <CodeWindow {...props} />,
}

const PostLayout = ({ children }) => {
    return <div>
        <MDXProvider components={components}>
            {children}
        </MDXProvider>
    </div>
}

Voila! Syntax highlighting for our mdx documents!

Bonus: Highlighting different languages

Mdx passes the string that's next to the triple backticks as a class of our custom component, language-${name}:

// source is the actual string inside the triple backticks
 const { props: { children: source, className: languageClass } } = children

// to get the actual name
 const language = classLanguage.replace(/language-/, '')

Then you can pass the language to the Highlight component:

<Highlight {...defaultProps} code={source} language="javascript">

How to add a blog to an existing Gatsby site

Cesar Varela — Sat, 31 Jul 2021 06:18:15 +0000

I decided to start a blog and keep a record of my development adventures.

I'm a to the point kind of guy so let's get to it:

Adding Mdx

Why MDX, you may ask? Markdown is great, but sometimes you need more expressiveness yet, especially for a development blog and if you want to do unique things. With MDX, you can write pure Markdown or go crazy and add React components everywhere (which I'm planning to do 🙌)

yarn add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

npm i --save  gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

You can now add the gatsby-plugin-mdx plugin to your gatsby-config.js :

plugins: [
`gatsby-plugin-mdx`
]

With this done, you can create your first post at src/blog/some-post-slug.mdx, and if you navigate to https://localhost:8000/blog/some-post-slug, you'll see your first post!

But it looks like 💩💩💩

Specifying a layout

The mdx plugin we just added lets you specify layout components for your mdx files. I'll only use mdx for my blog, so setting a default layout will be enough for me, but you can specify different configurations if you need to.

{ 
    resolve: `gatsby-plugin-mdx`, 
    options: { 
        defaultLayouts: {
            default: require.resolve("./src/components/PostLayout.js"),
        },
    },
},

Creating the layout

For a simple blog, you need nothing different from standard Gatsby layouts. You'll get the content of the post on the children property. The only part that needs special consideration is adding a list of the latest blog posts, for which you need three things:

1 - Add this to your `gatsby-config.js`:

Setup gatsby-source-filesystem to create nodes for the src/pages/blog folder (otherwise, they won't show in the next step):

{
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `posts`,
        path: `${__dirname}/src/pages/blog`,
      },
},

2 - Getting a list of the latest five posts sorted by date:


  const { allMdx } = useStaticQuery(graphql`
  query PostLayoutQuery {
    allMdx(sort: {fields: frontmatter___date, order: DESC}, limit: 6) {
      edges {
        node {
          frontmatter {
            title
            date
          }
          slug
        }
      }
    }
  }`)

Yes, because we want to show five posts and we'll always get the current post in the first place of the list, we'll ask for six and filter out the current one:

  const posts = allMdx.edges.filter(({ node }) => !location.pathname.includes(node.slug))

3 - Link to the other posts

It could look something like this:

 <List>
      {posts.map(({ node }) => <Item key={node.slug}>
        <Link to={`/blog/${node.slug}`}>
          {node.frontmatter.title}
        </Link>
      </Item>)}
    </List>

Wrapping up

This is good enough for the first version of a blog. I'll add custom components to show jsx better than I'm doing now in another post. We'll use gatsby-node.js to specify our custom frontmatter fields, create a custom slug URL, so we don't have to hardcode the /blog path in our links and more.

An example of the complete layout file (because I know you are looking for it)

PostLayout.js

import React from "react"
import { useStaticQuery, graphql, Link } from 'gatsby'

export default function PostLayout({ children }) {

    const data = useStaticQuery(graphql`
   query PostLayoutQuery {
    allMdx(sort: {fields: frontmatter___date, order: DESC}, limit: 6) {
      edges {
        node {
          frontmatter {
            title
            date
          }
          slug
        }
      }
    }
  }
  `)
    const posts = allMdx.edges.filter(({ node }) => !location.pathname.includes(node.slug))

    return <div>
        <main>
            {children}
            <h3>Latest posts</h3>
            <ul>
                {posts.map(({ node }) => <li key={node.slug}>
                    <Link to={`/blog/${node.slug}`}>
                        {node.frontmatter.title}
                    </Link>
                </li>)}
            </ul>
        </main>
    </div>
}