ooloth / gatsbytutorials.com Goto Github PK

Summary

Allow tutorials to include multiple formats (e.g. "text" and "video") instead of just one.

Motivation

• Sometimes, contributors want to categorize a tutorial's format as both "text" and "video" (e.g. for a blog post that include embedded video content)
• Since the format property is currently a string, contributors need to pick just one primary format, but this is sometimes less accurate than listing multiple formats
• I missed this issue on a tutorial submission that listed the format as "text, video", so the directory now includes a "text, video" format, which is clearly a bug
• The best solution (both logically and practically) is simply to drop the one format restriction

Approach

1. Rename all of the format fields in src/data/tutorials.yml to formats (i.e. add an "s")
2. Convert all of the formats values to an array of strings (rather than a single string)
3. Update the construction of the formats list to work with the new array format
4. Update the logic that assigns an emoji to each tutorial to one of the following:
   a. Show multiple emoji (accurate, but will make the layout inconsistent)?
   b. Choose a single emoji based on an emoji hierarchy (e.g. 📺 > 🎧 > ✍️)?
   c. Other logic? I'm open to suggestions here...
5. Update README.md instructions

Old syntax ❌

format: video

New syntax ✅

formats: 
- video

Summary

If possible, it would be great to create the lists used to populate the filter menus at build time rather than on the client side (as we currently do) since it would speed up the site's initial rendering time.

Motivation

• Lighthouse identifies 2.9s of main thread work when the page first loads and identifies "the time spent parsing, compiling and executing JS" as an area that could be improved
• Since these values only have to be calculated once and they never change, getting these calculations out of the way at build time just makes sense
• It's very "Gatsby" to try to do as much compilation of static assets and values at build time as possible so the site has less work at first load and can render quickly

Approach

• TBD
• I haven't confirmed yet whether it's possible to use gatsby-node.js to perform this kind of work and server-render the results
• The fact that the Gatsby Showcase performs a similar task on the client side as well is not encouraging, but I think it's still worth doing some research to see if it's possible

If you have any insights, please let me know!

Summary

The current filter logic uses a lot of Boolean flags and conditionals that are likely totally unnecessary. We should replace them with a more elegant (and less error-prone) solution.

Motivation

• This code is brittle and has way too many places where mistakes could be made
• This boolean-and-conditionals approach makes it hard to extend the filter functionality to add features like multiple active filters in each category (see #23)

Approach

• We can likely drop all the booleans and rely purely on array methods like filter, reduce and includes
• The Gatsby Showcase has a good example of this approach (although it only involves one category of filters)
• We could investigate merging all filters into one array for filtering purposes (in case it helps)
• We could also investigate whether filters are a good use case for a state chart (or parallel state charts) using a library like xstate and whether expressing the filter logic in that form would be more human-readable and maintainable in the long run

Related

#23 also suggests that array comparisons are a good direction to explore.

Summary

Currently, only one value can be selected in each filter category (i.e. only one format, one topic, one author and one source). We should make it possible to select multiple values from each category (e.g. filter for tutorials that match 3 topics).

Motivation

• Combinations of filters make it easier to narrow the list to exactly what you're looking for
• For topics in particular, I've often tried to use this feature (forgetting I haven't build it yet 🤣)

Approach

• Convert filter category states from string values to array values
• When a topic is clicked, add it to that filter category's array
• To filter the list, we'll check if each item's filter values contains every item in the related filter arrays in state

While this would most useful for topics (and maybe useless for sources), I think we might as well enable this behaviour for all filter categories to be consistent.

If you have suggestions for how to improve this approach, feel free to share!

Related

#28 is also exploring how to improve the filter logic implementation.

Summary

Reduce the number of DOM nodes on the page by not rendering out of view filter menu items.

Motivation

Speed up page load (Lighthouse is identifying the number of DOM nodes as a bottleneck).

Approach

Try using react-window for this.

Summary

On small screens, the tutorials take up the full width of the screen and the filters are accessed by opening a modal window that slides in from the right. We should make sure this modal component is as accessible as possible for all users.

Motivation

• @reach/dialog is more thoroughly tested for accessibility than other component libraries
• Screen reader accessibility in particular would be improved by swapping these libraries (please correct me if this is not accurate)

Alternatives

• Find a different way to access the filter lists on small screens so a modal window isn't necessary

Approach

• Install and import the @reach/dialog dependencies (JS + CSS)
• Create a copy of the modal with @reach/dialog and verify it looks and works the same way
• Remove the react-modal implementation and imports (JS + CSS)
• Uninstall react-modal

Summary

To improve the site's search results, we can replace the custom search logic with Fuse.js.

Motivation

There are currently two issues with the site's search logic:

1. Strings contained inside arrays (e.g. topics and authors) are excluded from the search
2. The search string must be an exact match (fuzzy or partial matches don't work)

Fuse solves both of these issues.

Approach

1. Refactor the combined filter-and-search logic into separate filter and search steps
2. Install and implement Fuse by following its docs
3. Refer to the Gatsby Showcase search implementation, which uses Fuse
4. Remove the non-Fuse search logic

Summary

Add a "Contributors" section to gatsbytutorials.com (below the filter lists) that includes each contributor's image and a link to their GitHub profile.

Motivation

• Contributors deserve recognition! 🎉
• More recognition might encourage others to contribute, which helps everyone 👍
• A bit more colour on the site wouldn't hurt 🎨

Challenges

• GitHub's GraphQL API (v4) doesn't currently allow querying contributors
• So, we'll need to query GitHub's REST API (v3)

Approach

• We could fetch the collaborators data on the client side...but come on now
• Instead, let's pull the data into Gatsby's GraphQL layer using the very handy gatsby-source-apiserver so we can server-side render the data and make it ready when the site first loads
  • Here's the main v3 API endpoint and the contributors endpoint for this repo
  • Since we're making a get request, the only options we should need to set are name and url
• Since Gatsby isn't able to process remote images, we can use gatsby-plugin-remote-images to download them, process them with sharp, and output them with gatsby-image

Styling

• The new section can be placed below the filter lists
• It probably makes sense to make the background the flat grey used at the top of the site (to make it clear the section isn't another filter list)
• The heading can just be "Contributors" (styled like the filter list headings)
• The photos can be shown at a small size in a grid similar to the one that pops up when hovering over the "15 contributors" link on this repo's main page

Summary

After converting the CSS from postcss to styled-components in #16, the two-column layout now sometimes jumps into place on large screens just after the page loads.

Motivation

• Nobody likes janky nonsense 😠

Approach

• I think this jump is likely caused by this media query helper, which uses JS that likely doesn't evaluate until after the page first renders (to be confirmed)
• An easy fix would be to replace this helper with an inline @media... query and hardcode the breakpoint value, but I'd prefer to pull the breakpoint from a central design system location if possible (for consistency)
• We use CSS variables for the rest of the design system values, but unfortunately media query values can't be stored this way...

I'll tinker with this soon. In the meantime, I'm open to suggestions!

Summary

When the site first loads, all 212+ tutorials are rendered immediately. This slows down the site's loading speed and is a problem that will only get worse as the directory grows, so we should choose an approach that helps limit the number of tutorials shown at one time.

Motivation

• According to Lighthouse, the DOM size when the page first loads (5,635 nodes) is well above the recommended max of 1,500 nodes
• As the Lighthouse audit explains, "A large DOM can increase memory usage, cause longer style calculations, and produce costly layout reflows."
• We wouldn't be building with Gatsby if we didn't care about loading speed, so let's fix it!

Approach

• A simple approach would be to limit the number of tutorials shown and let users click a "view more" button to view X more tutorials (this is the approach used by the Gatsby Showcase)
  • So, when the page first loads, limit the tutorials shown to ~15
  • Provide a "View more" button below the list and increase the limit by ~15 each time it is clicked
  • When a filter is clicked or a search is entered, reset the limit to ~15 (optional)
  • If applicable, show the "View more" button below the list again
• I generally like to use a state chart (via xstate) to track this kind of logic (optional)
• We can also use the source code for the Gatsby Showcase as a guide

Alternatives

• Instead of a "view more" button, we could provide a "view all" button to see show all hidden tutorials at once. (This is a bit nicer for user's who would rather scroll than click, but doesn't solve the excessive DOM nodes issue.)
• Instead of limiting the list, we could implement windowing. (My main concern with this approach has to do with styling. It looks like there are a number of restrictions that could make the look and feel of the directory awkward if we try to use this approach here.)
• Instead of limit + view more, we could implement infinite scroll. (This is a common approach on many sites (e.g. dev.to) and scrolling without having to click a button is fun, but if anyone is specifically trying to get to the footer...they will not have a good time. My loose understanding is that this is an accessibility no-no.)
• Instead of limit + view more, we could implement pagination. (While this works well for a stable list like a blog archive, I'm not sure a filterable list is a good use case.)

If you have thoughts or suggestions, feel free to share!

The site crashes when you type anything in search box.
Below is the error code received in browser console.

react-dom.production.min.js:4438 TypeError: Cannot read property 'toLowerCase' of undefined
    at Directory.js:93
    at Array.filter (<anonymous>)
    at Ae (Directory.js:19)
    at Xo (react-dom.production.min.js:3304)
    at Ci (react-dom.production.min.js:3775)
    at Li (react-dom.production.min.js:3987)
    at Ka (react-dom.production.min.js:5544)
    at qa (react-dom.production.min.js:5566)
    at Ru (react-dom.production.min.js:5988)
    at Cu (react-dom.production.min.js:5955)