[v1.0] Documentation improvements. #1370
Conversation
|
Deploy preview ready! Built with commit 93cf28b |
|
Deploy preview ready! Built with commit 93cf28b |
|
Deploy preview ready! Built with commit 93cf28b |
| * All Gatsby site UI is built with React components. | ||
| * Concise description of why components amazing model for building sites. | ||
| * Perhaps link to other good articles on "Why components are amazing". | ||
| You'll need to have basic understanding of React components. |
There was a problem hiding this comment.
Perhaps "To use Gatsby, you will need a basic understanding of React components"
|
|
||
| ## Why React components? | ||
|
|
||
| React allows to create big complicated webapps while preserving modularity, reusabilty, and clear abstraction. React also has great devtools available for debugging the applicattion. |
There was a problem hiding this comment.
React allows creating|building big...
|
|
||
| ## How does Gatsby use React Components? | ||
|
|
||
| Everything in Gatsby is built using Components. |
There was a problem hiding this comment.
lower-case c in components
|
|
||
| ### UI Layouts | ||
|
|
||
| `src/layouts/index.jsx` (optional) is a wrapper component for everything generated by Gatsby. You can use it to create consistent layouts between pages. |
There was a problem hiding this comment.
"wraps page components. You can use use it for site-wide parts of the site like headers and footers."
|
|
||
| ### Page generation | ||
|
|
||
| Components under `src/pages` are being automatically mapped to HTML files with respective paths. For example `src/pages/index.jsx` is mapped to `yoursite.com` meanwhile `src/pages/about.jsx` is `yoursite.com/about/`. |
There was a problem hiding this comment.
"mapped to pages with paths based on their file name"
|
|
||
| Everything in Gatsby is built using Components. | ||
|
|
||
| A basic directory structure of a project looks like this: |
There was a problem hiding this comment.
"might look like this:"
|
|
||
| You may have noticed that `src/pages/posts` also contains markdown files. You can transform any file into HTML pages using [Gatsby plugins](https://www.gatsbyjs.org/docs/plugins/). | ||
|
|
||
| ### Templates |
|
|
||
| ### Templates | ||
|
|
||
| `src/templates/post.jsx` (optional) is a component that queries GraphQL database for markdown information, and then generates HTML based on it. |
There was a problem hiding this comment.
is an example of a page component. It queries the GraphQL schema for markdown data and then renders the page using this data.
| ` | ||
| ``` | ||
|
|
||
| Please note, that for this to work, you'll also need to configure: |
There was a problem hiding this comment.
Replace this last section with something like: "These are examples of the different ways React components are used in Gatsby sites. To see full working examples, check out the examples directory in the Gatsby repo". And link that last bit.
|
My not so native english showed itself again... |
|
haha that's why you have an english-speaking editor! You supply the ideas and we supply the polished prose :-) |
|
thanks! |
This PR completes the
Building with Componentsdocumentation page.I tried to keep following the outline as much as I could, but ended up describing the whole project structure. I'm not completely sure whether that should be in the same page, or a different one.
Suggestions are welcome :)