diff --git a/docs/contributing/gatsby-style-guide.md b/docs/contributing/gatsby-style-guide.md index 9f6ea52e77a89..023e72e14e6b2 100644 --- a/docs/contributing/gatsby-style-guide.md +++ b/docs/contributing/gatsby-style-guide.md @@ -126,19 +126,45 @@ Hyperlinks should contain the clearest words to indicate where the link will lea ```markdown -[Gatsby's docs](https://www.gatsbyjs.org/docs/) +[Gatsby's docs](/docs/) -[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 + + +[Gatsby's glossay](/docs/glossary) + + + +[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 + + +open your site with `http://localhost:8000/` + + + +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."