Skip to content

Commit

Permalink
feat(docs): image and recipe docs updates (gatsbyjs#14803)
Browse files Browse the repository at this point in the history
* docs(images): add note about not needing GraphQL

* add recipe header instructions

* update heading levels for recipe categories
  • Loading branch information
Marcy Sutton committed Jun 15, 2019
1 parent e806c66 commit 609d613
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 9 deletions.
42 changes: 34 additions & 8 deletions docs/contributing/docs-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,9 +195,9 @@ Assume the reader has basic programming knowledge like the command line, code ed

## Recipes

[Docs Recipes](/docs/recipes/) should act as discoverable, concise instructions for completing common Gatsby tasks without having to navigate elsewhere. A recipe should include requirements and a few short steps to complete a task, listing actionable instructions inline and omitting everything else.
[Docs Recipes](/docs/recipes/) should act as discoverable, concise instructions for completing common Gatsby tasks without having to navigate elsewhere. A recipe should include requirements and a few short steps to complete a task, listing actionable instructions inline, and omitting everything else.

Recipes are smaller units than tutorials, each limited to a single feature or task. Multiple recipes could be linked from a reference guide or tutorial, however the content should be consolidated in the Recipes section for discoverability.
Recipes are smaller units than tutorials, each limited to a single feature or task. Multiple recipes could be linked from a reference guide or tutorial, however the content should be consolidated in the Recipes section for discoverability. If a recipe is recorded as a video, it should be less than five or ten minutes long.

The components of a recipe are:

Expand All @@ -208,18 +208,42 @@ The components of a recipe are:

Recipes should be short. If you're finding a recipe is becoming too long to fit on the Docs Recipes page due to including many prerequisites or steps, consider writing a tutorial instead.

### Recipe categories

Grouping recipes by topic will allow users to navigate and learn by subject matter. As recipes following the new format are introduced, you might find a section needs an h2 heading added for the group. The older-style recipes should be gradually replaced with actionable recipes following the template below.

Recipes should fall into these categories to start (suggest your idea in a GitHub issue!):

- Pages/Layouts
- Styling
- Starters
- Themes
- Sourcing
- Querying
- Images
- Transforming
- Deploying

Here's a template for a recipe category:

```markdown:title=docs/docs/recipes.md
## Category name
```

### Recipe template

````markdown
## Recipe name
When writing a recipe, try to include each of the below items wherever relevant.

### Requirements
````markdown:title=docs/docs/recipes.md
### Recipe name
#### Requirements
- A Gatsby site with two page components: `index.js` and `contact.js`
- The Gatsby <Link /> component
- The Gatsby CLI method `gatsby develop`
### Directions
#### Directions
1. Open the index page component (src/pages/index.js), import the <Link />
component from Gatsby, add a <Link /> component above the header, and give
Expand All @@ -240,8 +264,10 @@ export default () => (
2. Run `gatsby develop` and navigate to the index page. You should have a link
that takes you to the contact page when clicked!
// optional:
For a working example, check out **this example.**
#### Related links
- Any live demos
- Other materials to check out
````

## Tutorials
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/gatsby-image.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Gatsby Image API

Part of what makes Gatsby sites so fast is its recommended approach to handling images. `gatsby-image` is a React component designed to work seamlessly with Gatsby’s [native image processing](https://image-processing.gatsbyjs.org/) capabilities powered by GraphQL and [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/) to easily and completely optimize image loading for your sites.

> _Note: gatsby-image is **not** a drop-in replacement for `<img />`. It’s optimized for fixed width/height images and images that stretch the full-width of a container._
> _Note: gatsby-image is **not** a drop-in replacement for `<img />`. It’s optimized for responsive fixed width/height images and images that stretch the full-width of a container. There are also other ways to [work with images](/docs/images-and-files/) in Gatsby that don't require GraphQL._
Demo: [https://using-gatsby-image.gatsbyjs.org/](https://using-gatsby-image.gatsbyjs.org/)

Expand Down

0 comments on commit 609d613

Please sign in to comment.