Using files outside of src/

There is some demand for the behavior described in https://github.com/toastdotdev/toast/issues/50#issuecomment-751384350 to be handled automatically for files outside of src/. That is: you have a file outside of src/, how do you import it.

Right now the files that are served at the end of the day (that is, the files that end up in public/), are built from their one-to-one counterparts in src/ and static/. So to use that file outside of src/ you have to bring it into the site somehow. Introducing content-related files from outside src/ is done through setDataForSlug. An mdx file might be used as such, for example:

setDataForSlug("/some-post", {
  component: {
    mode: 'source',
    value: mdxContent
  }
});

aside: src/static order of operations

The order of operations similarly named files is not currently part of the public API. Basically this means that we do not guarantee the current behavior (when `static/thing.js` competes with `src/thing.js` for the `public/thing.js` slot, `static` wins). In general src/ and static should not conflict. `setDataForSlug` could also "compete" for a public/ slot in the worst case.

This also works for .js/etc files.

How could we make this more automatic?

Does it make sense to replicate the experience of webpack and other frameworks which associate file extensions with processing pipelines? this kind of happens by default for .js files in src/. We could theoretically "automatically" turn that on, which could enable handling .mdx files in src/ without running setDataForSlug like toast-tools/mdx does. It would be important to match the behavior of setDataForSlug though, so as to not create the "src/pages" vs "src/" behavioral differences in other frameworks.

@toastdotdev/mdx allows you to pull in mdx from anywhere. One such location (to give a concrete example) is a content folder inside of the site.

People are then confused as to how to import other files, both next to the current file and from the site itself.

There is no technical issue here (if you do it right, it works), but the user experience could be better (if you do it wrong, you can get stuck in confusing situations)

The mental model is that imports are written as they will be executed on the resulting site. This is different than the mental model of other frameworks (like those built on webpack) for which imports point to other source files and the user expects the imports to be transformed to work on the final site. It is possible that we should swap to this model.

toastdotdev / toast

Using files outside of src/ #55