Skip to content

Commit

Permalink
fix
Browse files Browse the repository at this point in the history
  • Loading branch information
muescha committed Mar 1, 2020
1 parent 22ead19 commit e07838c
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's docs](/docs/)

<!-- Bad -->

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

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

Hyperlinks which point to the same domain should have relative path (not include the domain). This is usefully when you test the build of the website on a local installations or on preview builds from your build system.

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

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

<!-- Bad -->

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

Note: Links to the Gatsby Cloud / Gatsby Inc. are at located at [gatsbyjs.com](https://www.gatsbyjs.com/) and should be absolute an path (include the domain). 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 e07838c

Please sign in to comment.