diff --git a/docs/docs/gatsby-project-structure.md b/docs/docs/gatsby-project-structure.md index 1e1dd206b2845..e6d202b777d3e 100644 --- a/docs/docs/gatsby-project-structure.md +++ b/docs/docs/gatsby-project-structure.md @@ -1,51 +1,51 @@ - --- - title: Gatsby Project Structure - --- +--- +title: Gatsby Project Structure +--- Inside a Gatsby project, you may see some or all of the following folders and files: ``` -/ -|-- /.cache -|-- /plugins -|-- /public -|-- /src - |-- /pages - |-- /templates - |-- html.js -|-- /static -|-- gatsby-config.js -|-- gatsby-node.js -|-- gatsby-ssr.js -|-- gatsby-browser.js +/ +|-- /.cache +|-- /plugins +|-- /public +|-- /src + |-- /pages + |-- /templates + |-- html.js +|-- /static +|-- gatsby-config.js +|-- gatsby-node.js +|-- gatsby-ssr.js +|-- gatsby-browser.js ``` ### Folders -- **`/.cache`** *Automatically generated.* This folder is an internal cache created automatically by Gatsby. The files inside this folder are not meant for modification. Should be .gitignore-d. +- **`/.cache`** _Automatically generated._ This folder is an internal cache created automatically by Gatsby. The files inside this folder are not meant for modification. Should be .gitignore-d. -- **`/public`** *Automatically generated.* The output of `gatsby build` process will be exposed inside this folder. Should be .gitignore-d. +- **`/public`** _Automatically generated._ The output of `gatsby build` process will be exposed inside this folder. Should be .gitignore-d. - **`/plugins`** This folder hosts any project-specific ("local") plugins that aren't published as an `npm` package. Check out the [plugin docs](/docs/plugins/) for more detail. - **`/src`** This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser), like your site header, or a page template. “Src” is a convention for “source code”. - - **`/pages`** Components under src/pages become pages automatically with paths based on their file name. Check out the [pages docs](/docs/recipes/#creating-pages) for more detail. - - **`/templates`** By convention, templates used across multiple pages are Contains templates for programmatically creating pages. Check out the [templates docs](/docs/building-with-components/#page-template-components) for more detail. - - **`html.js`** For custom configuration of default .cache/default_html.js. Check out the [custom html docs](/docs/custom-html/) for more detail. + + - **`/pages`** Components under src/pages become pages automatically with paths based on their file name. Check out the [pages docs](/docs/recipes/#creating-pages) for more detail. + - **`/templates`** By convention, templates used across multiple pages are Contains templates for programmatically creating pages. Check out the [templates docs](/docs/building-with-components/#page-template-components) for more detail. + - **`html.js`** For custom configuration of default .cache/default_html.js. Check out the [custom html docs](/docs/custom-html/) for more detail. - **`/static`** If you put a file into the static folder, it will not be processed by Webpack. Instead it will be copied into the public folder untouched. Check out the [assets docs](https://www.gatsbyjs.org/docs/adding-images-fonts-files/#adding-assets-outside-of-the-module-system) for more detail. ### Files - **`gatsby-browser.js`**: This file is where Gatsby expects to find any usage of the [Gatsby browser APIs](/docs/browser-apis/) (if any). These allow customization/extension of default Gatsby settings affecting the browser. - + - **`gatsby-config.js`**: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. Check out the [config docs](/docs/gatsby-config/) for more detail. - + - **`gatsby-node.js`**: This file is where Gatsby expects to find any usage of the [Gatsby node APIs](/docs/node-apis/) (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process. - + - **`gatsby-ssr.js`**: This file is where Gatsby expects to find any usage of the [Gatsby server-side rendering APIs](/docs/ssr-apis/) (if any). These allow customization of default Gatsby settings affecting server-side rendering. ### Miscellaneous: The file/folder structure described above reflects Gatsby-specific files and folders. Since Gatsby sites are also React apps, it's common to use standard React code organization patterns such as folders like `/components` and `/utils` inside `/src`. The [React docs](https://reactjs.org/docs/faq-structure.html) have more information on a typical React app folder structure. - diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md index 4d5d4aa3ab8e8..87a9d699955c9 100644 --- a/docs/docs/recipes.md +++ b/docs/docs/recipes.md @@ -28,6 +28,7 @@ Craving a happy medium between doing the [full tutorial](/tutorial/) and crawlin - [Querying data](#querying-data) - [Sourcing data](#sourcing-data) - [Transforming data](#transforming-data) +- [Gatsby project structure](#gatsby-project-structure) ## Using Unstructured Data @@ -36,6 +37,10 @@ You can use the node `createPages` API to pull unstructured data into Gatsby sit - Learn how to pull unstructured data into Gatsby sites in [Using Unstructured Data](/docs/using-unstructured-data/) - Learn when and how to use GraphQL and source plugins for more complex Gatsby sites in [Querying data with GraphQL](/docs/querying-with-graphql/) +## Gatsby project structure + +Read the [Gatsby project structure](/docs/gatsby-project-structure/) guide for a tour of the folders and files you may see inside a Gatsby project. + ## Using a starter Starters are boilerplate Gatsby sites maintained officially, or by the community. diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index f1861287f1ba7..7984c4c89c4a0 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -71,8 +71,8 @@ - title: Sourcing content and data* link: /docs/content-and-data/ items: - - title: Unstructured Data - link: /docs/unstructured-data/ + - title: Using Unstructured Data + link: /docs/using-unstructured-data/ - title: Sourcing from the filesystem* link: /docs/sourcing-from-the-filesystem/ - title: Sourcing from databases* @@ -257,6 +257,8 @@ items: - title: The Gatsby core philosophy* link: /docs/gatsby-core-philosophy/ + - title: Gatsby project structure + link: /docs/gatsby-project-structure/ - title: Life and times of a Gatsby build* link: /docs/life-and-times-of-a-gatsby-build/ - title: Building with components