There are many ways you can find the Notion files property useful. One of the experiments I did was using it to provide a hero image for my blog. Currently, hero images from all blog posts come for a Hero Image files property I have on my DB. In general, the process is quite straightforward. Here's an example with MarkdownRemark that pulls in images for all notion pages, assuming that the files property we need is called Hero Image:

query {
  allMarkdownRemark {
    edges {
      node {
        remoteImage {
          childImageSharp {
            gatsbyImageData(layout: FIXED)
          }
        }
      }
    }
  }
}

But there are things you need to consider.

✅ Embedding files via links

If you embed files via links, it should work out just fine with MarkdownRemark or MDX. gatsby-source-notion-api will create remote file nodes for those images. You can then use Sharp to transform them and do any other stuff you would do with images in Gatsby. All you need to do is to query for the image and put it where you need it.

💥 Uploading files

If you upload files, things get a bit trickier. The thing is that Notion API returns only the name of the asset if you upload it, not the URL where it resides. There are two ways you can bypass this

Storing attached images in the project repository

You could potentially attach images to a Notion page and then also copy them to your project folder, and then find the Notion attachment in the list of files you have in the repo, but this approach is quite funny and I didn't try it out. Maybe it could help in some cases. But, again, maintain it here and there if you do this.

Uploaded files are in fact links

After you attach a file, you can use the kebab menu (three dots) near the image and click "View original". It will open your image in a new tab. All you need to do is to copy the link and attach it to the same property. It is observed that you can remove the initial file afterward and the embedded link will still lead you to the file correctly. I don't know for how long they cache assets and if they remove them when you remove the attachment or not, but for now and for me it works.

UPD: Don't remove the file, simply move it down in the attachments, so that attachments as links are always on top.

After you have a file attached as a link, you can be sure that everything will work. 🎉