Gatsby: [docs] [workflows] Improve docs for "Working with fonts and typography"

[nicholaspung]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

User story

As a new Gatsby user, I want to work with fonts and typography in my Gatsby project.

Evaluation

Search | Discover | Complete | Linked | Tone | Style | Overall
-- | -- | -- | -- | -- | -- | --
😄 | 😄 | 😐 | 😄 | 😄 | 😐 | 😐

Steps taken to implement

1. Searchability

   • Gatsby fonts and typography
     
     
     
     1. result: https://www.gatsbyjs.org/docs/typography-js/
     
     
   • Gatsby fonts
     
     
     
     1. result: https://www.gatsbyjs.org/packages/gatsby-plugin-web-font-loader/
     
     
   • Gatsby typography
     
     
     
     1. result: https://www.gatsbyjs.org/docs/typography-js/
     
     
     2. result: https://www.gatsbyjs.org/packages/gatsby-plugin-typography/
     
     
     3. result: https://www.gatsbyjs.org/guidelines/typography/
     
     
   • Gatsby change font
     
     
     
     1. result: https://www.gatsbyjs.org/docs/typography-js/
     
     
     2. result: https://www.gatsbyjs.org/packages/gatsby-plugin-web-font-loader/
     
     
   • Gatsby change typography
     
     
     
     1. result: https://www.gatsbyjs.org/docs/typography-js/
     
     

2. Discoverability

   • Search bar:

     • fonts:
       
       
       
       1. result: https://www.gatsbyjs.org/docs/recipes/#adding-a-local-font
          
          
          
          
          
          • only recipes for fonts shows up
          
          
          
       
       
     • typography
       
       
       
       1. result: https://www.gatsbyjs.org/docs/typography-js/
          
          
          
          
          
          • all results go to typography-js docs
          
          
          
       
       
     • fonts and typography
       
       
       
       1. results: https://www.gatsbyjs.org/docs/typography-js/
       
       
       2. blogs:
          
          
          
          
          
          • 1 article not related to fonts and typography
          
          
          
          • 1 article links to importing images, fonts, and files
          
          
          
          • no article on using CSS modules/CSS in JS
          
          
          
       
       

   • Clickpath on .org:

     • docs -> recipes -> styling with css -> adding a local font/ using google fonts -> scroll down to additional resources - typography.js
     • docs -> tutorial -> introduction to styling in gatsby
     • docs -> reference guides -> styling your site
     • no clear clickpath to get to /importing-assets-into-files/

3. Completeness

   • https://www.gatsbyjs.org/docs/recipes/#adding-a-local-font
     
     
     
     • when following steps, using a Gatsby starter template, need to make sure the font name overrides (regular cascading style)
     
     
     • [rec] Include instructions to follow regular CSS rules. For beginners, maybe recommend to override default CSS fonts beforehand
     
     
   • https://www.gatsbyjs.org/docs/typography-js/
     
     
     
     • [rec] when following steps, need to add instructions to remove previous font/typography styling in CSS, otherwise typography doesn't work | GitHub issue regarding this
     
     

4. Linkedness

   • Links to Typography GitHub,
     
     
     
     • [rec] add https://www.gatsbyjs.org/packages/gatsby-plugin-typography/
     
     
   • Links to adding files to static folder, gatsby-source-filesystem for querying, information about data uri
   • Links to importing assets into files

5. Tone and accessibility

   • Informative, prerequites are clear

6. Style

   • In Typography.js, writing is currently grade 12 judged by hemingwayapp (goal is grade 6)

Recommendations

• [ ] Add SEO to local fonts page for people searching how to change fonts - Covered by Issue #21277
  
  
  
  • [ ] If reference guide doesn't pop up in SEO, write a blog post showcasing how to use fonts (host with Medium)
  
  
• [x] [Import Assets Into Files](https://www.gatsbyjs.org/docs/importing-assets-into-files/): Include an example of importing a font, or link to local fonts page
• [x] [Add Local Fonts](https://www.gatsbyjs.org/docs/recipes/#adding-a-local-font): Include instructions to follow regular CSS rules. For beginners, maybe recommend to override default CSS fonts beforehand
• [x] [Typography.js](https://www.gatsbyjs.org/docs/typography-js/): Simplify instructions to grade 6 level.
• [x] [Typography.js](https://www.gatsbyjs.org/docs/typography-js/): When following steps, need to add instructions to remove previous font/typography styling in CSS, otherwise typography doesn't work | GitHub issue regarding this
  
  
  
  • [x] Line highlight the added code in "installing typography themes" section
  
  
  • [x] gatsby-plugin-typography options references injecting fonts into JS or use a CDN of your choosing saying we have to include appropriate fonts yourself. Add link to adding a local font page or change wording as instructions are a bit confusing
  
  
  • [x] Explicitly say omitGoogleFont is optional. Also recommend changing the wording
  
  
• [ ] Create a reference guide with all fonts and typography information - Covered by #21280

[gillkyle]

These recommendations are awesome @nicholaspung! Really in depth and some great points. Like was noted in the meta issue (#13708), having a reference guide that can aggregate a lot of the information around fonts and typography would be really awesome to link to and just generally have available. Thanks for working on this workflow 🎉

Don't hesitate to reach out if you need any help 🙂

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[marcysutton]

cc @laurieontech, since we talked about fontawesome earlier! People often search for it on gatsbyjs.org and there is no result. Including that topic as part of "Working with fonts and typography" would be a way to slot in a doc on fontawesome/other libraries as part of a broader learning workflow.

[laurieontech]

Going to close this issue as we now have two open issues that cover the remaining recommendations.