Gatsby: What is the purpose of 'basePath' in 'createFilePath' when it has no affect on the returned value?

[MaxMcKinney]

So I've got a series of markdown files in a work folder. This is more of a question rather than an issue, but I'm confused as to how createFilePath works.

// Look at every node when it is created
exports.onCreateNode = ({node, getNode, actions}) => {
    // Check for markdown nodes
    const { createNodeField } = actions;
    if(node.internal.type === 'MarkdownRemark') {
        // Create a slug out of the markdown filepath name
        const slug = createFilePath({
            node,
            getNode,
            basePath: 'test'
        });
        console.log(slug)
        // Add the newly created slug to the node itself
        createNodeField({
            node,
            name: 'slug',
            value: slug
        });
    }
};

So I have basePath set to "test" currently. It stills works just fine. It finds the markdown files, outputs the name of the markdown file and then I can use that to make a slug. If I wish to prefix the slug with something I would do that in the createNodeField under value.

I would ASSUME that using basePath would either remove or add that path from the releativePath. Like if those markdown files were in that 'work' folder as I mentioned, why isn't the 'work' part of the path returned? I would assume if I left basePath empty that it would return the whole relative path of the file. However if I set the basePath to something then it would remove that from the returned value. How does this work? Why can I put anything I want there, like "test" and have it still work? The docs are really lacking in explaining it.

[wardpeet]

Feel free to help us document what's missing. I'll try to do my best to explain what's happening here.

Short answer, base-path removes that path from your path.

You should check the markdown's relativePath, it depends on how you setup gatsby-source-filesystem. With that, it tries to calculate a relative path from the basePath to the file's relative path and use returns that value.

Let me give an example that hopefully clarifies it. I'll be using https://github.com/gatsbyjs/gatsby-starter-blog as an example

Gatsby config has this setup:
https://github.com/gatsbyjs/gatsby-starter-blog/blob/07e5c8b7631395d611e1405255d8192b789da6f3/gatsby-config.js#L15-L21

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

You have blog posts located in content/blog/, for example: content/blog/hello-world/index.md.
Because we set the path to content/blog our relativePaths on fileNodes are hello-world/index.md. So, any base-path won't really have an effect because the result will always be /hello-world/

When does a base-path make sense?
I'll change above configuration to:

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

Now my relative fileNodes are starting with blog/. So if I run the the createFilePath now, all slugs will have a blog prefix. If I don't want to have a blog prefix I'll have to pass in the basePath: blog/ as by default the basePath is src/pages

[github-actions[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 60 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here.
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜