chore(docs): added note about shorter titles and breadcrumbTit… (#16438)

* chore: added note about shorter titles and breadcrumbTitle * fix: sophisticated punctuation
gatsbyjs · Aug 7, 2019 · 2bd0a25 · 2bd0a25
1 parent c22616e
commit 2bd0a25
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 0 deletions.
diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md
@@ -79,6 +79,16 @@ If you wrote a new document that was [previously a stub](/contributing/how-to-wr
   ...
 ```
 
+3. (Optional) if the name of the title seems long, consider adding a `breadcrumbTitle` to the entry in the `doc-links.yaml` file that is a shorter version of the title, and will show up in the breadcrumb on the docs page instead.
+
+```diff:title=www/src/data/sidebars/doc-links.yaml
+  ...
+  - title: Really, Really Long Example Document or Guide Title
+    link: /docs/example-document/
++   breadcrumbTitle: Shorter Title to Display
+  ...
+```
+
 ## Docs site setup instructions
 
 After going through the development setup instructions above, there are a few additional things that are helpful to know when setting up the [Gatsby.js docs site](/docs/). which mostly lives in the [www](https://github.com/gatsbyjs/gatsby/tree/master/www) directory.

diff --git a/docs/contributing/gatsby-style-guide.md b/docs/contributing/gatsby-style-guide.md
@@ -196,6 +196,8 @@ Article header or subhead:
 
 > Salty, sweet, and spicy
 
+Titles should aim to be brief while still conveying a comprehensive meaning of the article; headings have more leeway in terms of length. Because titles show up throughout the docs in navigation elements (like breadcrumbs, and sidebar navigation) there is a preference for shorter names to help mitigate visual clutter.
+
 ### Format code blocks, inline code, and images
 
 Use the following as reference when creating and editing docs: