static/img vs docs/assets—what's the difference?

[mpoundstone]

I noticed the different documentation for storing assets in static/img vs docs/assets/

Is there a major difference in how Docusaurus parses or loads assets stored in either folder? I know that files stored in static are copied over into the build folder when the command is run, but are files in docs/assets treated any differently?

[Josh-Cena]

Files not in the static folder will need you to require them so they enter Webpack's bundling pipeline and get emitted. They will end up in the build/assets/images folder and will be hashed. If you have some loader configured for Webpack, these images may also be minified / cropped, while images from static are always copied as-is and you can directly use URLs to reference them without require. (In fact if you require an image in static directory two copies would be created, one at the build root and one as asset)

[slorber]

👍

Also relevant issue/discussion: #5362

There's no special docs/assets in Docusaurus. There was in v1, not anymore in v2. You can put files anywhere and import/require them with JSX. We automatically convert md relative images and file links to require/import calls for you, so that you can easily co-locate static assets close to the docs using them, so that the static folder does not become a big messy folder over time.

[mpoundstone]

Gotcha, thank you both!