Fill out "Sourcing from the filesystem" stub article (#8777)

This issue (#8730) is part of the content migration project [#8103](#8103), which is meant to take existing content and repurpose it so it's easier to find in the docs.
gatsbyjs · Oct 30, 2018 · ef998ab · ef998ab
1 parent 23722c2
commit ef998ab
Show file tree

Hide file tree

Showing 7 changed files with 69 additions and 3 deletions.
diff --git a/docs/docs/images/allfile-query.png b/docs/docs/images/allfile-query.png
diff --git a/docs/docs/images/data-in-console.png b/docs/docs/images/data-in-console.png
diff --git a/docs/docs/images/filesystem-autocomplete.png b/docs/docs/images/filesystem-autocomplete.png
diff --git a/docs/docs/images/filesystem-query.png b/docs/docs/images/filesystem-query.png
diff --git a/docs/docs/images/graphiql-filesystem.png b/docs/docs/images/graphiql-filesystem.png
diff --git a/docs/docs/images/my-files-page.png b/docs/docs/images/my-files-page.png
diff --git a/docs/docs/sourcing-from-the-filesystem.md b/docs/docs/sourcing-from-the-filesystem.md
@@ -2,7 +2,73 @@
 title: Sourcing from the Filesystem
 ---
 
-This is a stub. Help our community expand it.
+This guide will walk you through sourcing data from the filesystem.
 
-Please use the [Gatsby Style Guide](/docs/gatsby-style-guide/) to ensure your
-pull request gets accepted.
+## Setup
+
+This guide assumes that you have a Gatsby project set up. If you need to set up a project, please reference the [Quick Start Guide](https://github.com/gatsbyjs/gatsby/tree/master/docs).
+
+It will also be useful if you are familiar with [Graph_i_QL](/docs/introducing-graphiql/), a tool that helps you structure your queries correctly.
+
+## Using `gatsby-source-filesystem`
+
+`gatsby-source-filesystem` is the Gatsby plugin for creating File nodes from the file system.
+
+Install the plugin at the root of your Gatsby project:
+
+```sh
+npm install --save gatsby-source-filesystem
+```
+
+Then add it to your project's `gatsby-config.js` file:
+
+```javascript{6-12}:title=gatsby-config.js
+module.exports = {
+  siteMetadata: {
+    title: `Your Site Name`,
+  },
+  plugins: [
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `src`,
+        path: `${__dirname}/src/`,
+      },
+    },
+  ],
+}
+```
+
+Save the `gatsby-config.js` file, and restart the Gatsby development server.
+
+Open up Graph_i_QL.
+
+If you bring up the autocomplete window, you'll see:
+
+![graphiql-filesystem](images/graphiql-filesystem.png)
+
+Hit <kbd>Enter</kbd> on `allFile` then type <kbd>Ctrl + Enter</kbd> to run a
+query.
+
+![filesystem-query](images/filesystem-query.png)
+
+Delete the `id` from the query and bring up the autocomplete again (<kbd>Ctrl +
+Space</kbd>).
+
+![filesystem-autocomplete](images/filesystem-autocomplete.png)
+
+Try adding a number of fields to your query, pressing <kbd>Ctrl + Enter</kbd>
+each time to re-run the query. You'll see something like this:
+
+![allfile-query](images/allfile-query.png)
+
+The result is an array of File "nodes" (node is a fancy name for an object in a
+"graph"). Each File object has the fields you queried for.
+
+## Transforming File nodes
+
+Once files have been sourced, various "transformer" plugins in the Gatsby ecosystem can then be used to transform File nodes into various other types of data. For example, a JSON file can be sourced using `gatsby-source-plugin`, and then the resulting File nodes can be transformed into JSON nodes using `gatsby-transformer-json`.
+
+## Further reference and examples
+
+For further reference, you may be interested in checking out the `gatsby-source-filesystem` [package README](https://www.gatsbyjs.org/packages/gatsby-source-filesystem/), and various official and community [starters that use the plugin](/starters/?d=gatsby-source-filesystem).