Skip to content

Commit

Permalink
docs(style guide): new section about internal links (#21871)
Browse files Browse the repository at this point in the history
* fix

* Update docs/contributing/gatsby-style-guide.md

Co-Authored-By: LB <laurie@gatsbyjs.com>

* Update docs/contributing/gatsby-style-guide.md

Co-Authored-By: LB <laurie@gatsbyjs.com>

* full url

Co-authored-by: LB <laurie@gatsbyjs.com>
Co-authored-by: gatsbybot <mathews.kyle+gatsbybot@gmail.com>
  • Loading branch information
3 people committed Mar 6, 2020
1 parent c6a712c commit 1a09edb
Showing 1 changed file with 28 additions and 2 deletions.
30 changes: 28 additions & 2 deletions docs/contributing/gatsby-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,19 +126,45 @@ Hyperlinks should contain the clearest words to indicate where the link will lea
```markdown
<!-- Good -->

[Gatsby's docs](https://www.gatsbyjs.org/docs/)
[Gatsby Cloud](https://www.gatsbyjs.com/cloud/)

<!-- Bad -->

[here](https://www.gatsbyjs.org/docs/ "Gatsby's docs")
[here](https://www.gatsbyjs.com/cloud/ "Gatsby Cloud")
```

In tutorials that are meant for beginners, use as few hyperlinks as possible to minimize distractions. In docs, it's ok to include as many hyperlinks as necessary to provide relevant and interesting information and resources.

### Use relative hyperlinks for local links

When referencing another page within [gatsbyjs.org](https://www.gatsbyjs.org/) hyperlinks should use relative paths (not include the full domain). This guarantees that all links function when running locally or in preview.

```markdown
<!-- Good -->

[Gatsby's glossay](/docs/glossary)

<!-- Bad -->

[Gatsby's glossay](https://www.gatsbyjs.org/docs/glossary)
```

Note: Links to Gatsby Cloud/Gatsby Inc. are located at [gatsbyjs.com](https://www.gatsbyjs.com/) and should be referenced using an absolute path (domain included). See also [Referencing Gatsby Cloud](#referencing-gatsby-cloud)

### Mark localhost URLs as code strings

Unless you're running `gatsby develop` or `gatsby build` locally, localhost links will not work. Therefore it's recommended to list these URL references as code blocks so there aren't invalid links throughout the docs on Gatsbyjs.org.

```markdown
<!-- Good -->

open your site with `http://localhost:8000/`

<!-- Bad -->

open your site with [http://localhost:8000/](http://localhost:8000/)
```

### Indicate when something is optional

When a paragraph or sentence offers an optional path, the beginning of the first sentence should indicate that it's optional. For example, "if you'd like to learn more about xyz, see our reference guide" is clearer than "Go to the reference guide if you'd like to learn more about xyz."
Expand Down

0 comments on commit 1a09edb

Please sign in to comment.