From 93dfe1002f6be3a0d24d2e573f6613b2236f53b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ros=C3=A1rio=20Pereira=20Fernandes?= Date: Tue, 30 Oct 2018 16:32:49 +0200 Subject: [PATCH] docs: fill out static folder stub (#9287) * docs: fill out "static folder" stub article * pluralized library --- docs/docs/adding-images-fonts-files.md | 4 +- docs/docs/static-folder.md | 72 ++++++++++++++++++++++++-- www/src/data/sidebars/doc-links.yaml | 2 +- 3 files changed, 71 insertions(+), 7 deletions(-) diff --git a/docs/docs/adding-images-fonts-files.md b/docs/docs/adding-images-fonts-files.md index c4ad049203674..7d8a0a179f177 100644 --- a/docs/docs/adding-images-fonts-files.md +++ b/docs/docs/adding-images-fonts-files.md @@ -108,9 +108,7 @@ query($slug: String!) { ## Using the `static` Folder -### Adding Assets Outside of the Module System - -You can also add other assets to a `static` folder at the root of your project. +You can also add other assets to a `static` folder at the root of your project. Check the [static folder](/docs/static-folder/) page to learn more. Note that we normally encourage you to `import` assets in JavaScript files instead. This mechanism provides a number of benefits: diff --git a/docs/docs/static-folder.md b/docs/docs/static-folder.md index d60fbad740d87..bee2d6a7972d3 100644 --- a/docs/docs/static-folder.md +++ b/docs/docs/static-folder.md @@ -2,7 +2,73 @@ title: Static folder --- -This is a stub. Help our community expand it. +In general, every website needs assets: images, stylesheets, scripts, etc. When using Gatsby, we recommend + [Adding Images, Fonts, and Files](/docs/adding-images-fonts-files/) in JavaScript files, + because of the benefits it provides: -Please use the [Gatsby Style Guide](/docs/gatsby-style-guide/) to ensure your -pull request gets accepted. +- Scripts and stylesheets are minified and bundled together to avoid extra + network requests. +- Missing files cause compilation errors instead of 404 errors for your users. +- Result filenames include content hashes so you don’t need to worry about + browsers caching their old versions. + +However, there is an **escape hatch** that you can use to add an asset outside of +the module system. + +## Adding Assets Outside of the Module System + +You can create a folder named `static` at the root of your project. Every file + you put into that folder will be copied into the `public` folder. E.g. if you + add a file named `sun.jpg` to the static folder, it'll be copied to + `public/sun.jpg` + +### Referencing your static asset + +In order to reference assets from the `static` folder in your code, you'll need to +[import the `withPrefix` helper function from `gatsby`](/docs/gatsby-link/#prefixed-paths-helper): +```js +import { withPrefix } from 'gatsby' + +render() { + // Note: this is an escape hatch and should be used sparingly! + // Normally we recommend using `import` for getting asset URLs + // as described in the “Adding Images, Fonts, and Files” page. + return Logo; +} +``` + +And make sure you +[set `pathPrefix` in your gatsby-config.js](/docs/path-prefix/): + +```javascript:title=gatsby-config.js +module.exports = { + // Note: it must *not* have a trailing slash. + pathPrefix: `/img`, +} +``` + + +### Downsides + +Keep in mind the downsides of this approach: + +- None of the files in `static` folder get post-processed or minified. +- Missing files will not be called at compilation time, and will cause 404 + errors for your users. +- Result filenames won’t include content hashes so you’ll need to add query + arguments or rename them every time they change. + +## When to Use the `static` Folder + +Normally we recommend importing [stylesheets](/docs/adding-images-fonts-files/#adding-a-stylesheet), +[images, and fonts](/docs/adding-images-fonts-files/#adding-images-and-fonts) from JavaScript. The `static` +folder is useful as a workaround for a number of less common cases: + +- You need a file with a specific name in the build output, such as + [`manifest.webmanifest`](https://developer.mozilla.org/en-US/docs/Web/Manifest). +- You have thousands of images and need to dynamically reference their paths. +- You want to include a small script like + [`pace.js`](http://github.hubspot.com/pace/docs/welcome/) outside of the + bundled code. +- Some libraries may be incompatible with Webpack and you have no other option but + to include it as a `