enhancement (docs): Improvements to retext-spell

[tesseralis]

Overview

This issue is an overview of improvements to standardizing the spelling and formatting of words in our docs. Fixing these involves going to dictionary.txt and removing unneeded entries.

1. put filenames like .htaccess in code blocks
2. put code like inferInputObjectStrctureFromNodes in code blocks
3. put names of packages (including gatsby plugins like gatsby-source-filesystem) in code blocks
4. Standardize names of libraries and brands (for example, GraphQL instead of Graphql or graphQL)
5. some image alt text in tutorial pages are just file names (e.g. ![with-layout2](with-layout2.png))

Note:

• if the lowercased word in dictionary.txt then both words are valid
• if only the Capitalized word in dictionary.txt than the lowercased is forbidden
• to forbid a word or only allow the lowercased word then mark the word with an asterisk (Example: see fix(docs): dictionary.txt -> fix brand name -> Webpack - webpack #25681 for webpack)

Upstream Changes

The following involve changes to retext itself and requires raising issues to that library:

7. Improve handling of words with numbers in them. "1000px" should be treated as the tokens "1000" and "px".
8. Improve handling of words-joined-with-dashes. These should be treated as individual words.
9. Syntax for hashtags

Current Activities

• dictionary.txt clean up:

  • .babelrc (@FocalChord in enhancement(docs): dictionary.txt -> .babelrc -> File names in code blocks #25585) (1: file names)
  • .env and more file extensions (@tesseralis in fix(docs) Add backticks on file extensions in docs #25665)
  • .htaccess (@FocalChord in enhancement(docs): dictionary.txt -> .htaccess -> File names in code blocks #25321) (1: file names)
  • .yml (@FocalChord in enhancement(docs): dictionary.txt -> .yml -> File names in code blocks #25584) (1: file names)
  • allfile-query (@meyian in enhancement(docs): Remove entries in dictionary.txt and fix alt text values in docs files #26022) (5: image alt text)
  • ASKGatsbyJS (@muescha in enhancement(docs): dictionary.txt -> fix tiwtter name -> AskGatsbyJS #26297) (4: brand names)
  • Codepen -> CodePen (@muescha in enhancement(docs): dictionary.txt -> CodePen -> fix brand name #25875) (4: brand names)
  • Codepen -> CodePen (@muescha in enhancement(docs): dictionary.txt -> CodePen -> fix brand name #25875) (4: brand names)
  • excited-gif (@meyian in enhancement(docs): Remove excited.gif from the dictionary #26304) (5: image alt text)
  • filesystem-query (@meyian in enhancement(docs): Remove entries in dictionary.txt and fix alt text values in docs files #26022) (5: image alt text)
  • Graphiql & GraphiQl(@tesseralis in fix(docs): Proper spelling of GraphiQL #25664) (4: brand names)
  • graphql (@FocalChord in enhancement(docs): standardising graphQL and Graphql into GraphQL in README files #25586|@muescha in enhancement(docs): dictionary.txt -> grapqhl -> brand name #25626) (4: brand names)
  • graphiql-filesystem (@meyian in enhancement(docs): Remove entries in dictionary.txt and fix alt text values in docs files #26022) (5: image alt text)
  • infer* (@FocalChord in enhancement(docs): dictionary.txt -> Infer* -> putting all code prefixed with infer into code blocks #25339) (2: code)
  • markdown-autocomplete (@meyian in enhancement(docs): Fix alt texts in docs/tutorial/part-six/index.md #25841) (5: image alt text)
  • npm + *NPM enforce npm in small letters (@muescha in enhancement(docs): dictionary.txt -> fix brand name -> NPM -> npm #25355) (4: brand names)
  • poject fix word (@muescha in enhancement(docs): dictionary.txt -> poject -> remove #25844)
  • *Webpack + *Webpacks enforce webpack in small letters (@muescha in fix(docs): dictionary.txt -> fix brand name -> Webpack - webpack #25681) (4: brand names)
  • with-layout2 (@meyian in enhancement(docs): dictionary.txt -> with-layout2 -> Remove file name from image alt text and dictionary #25358) (5: image alt text)
  • with-navigation2 (@meyian in enhancement(docs): dictionary.txt -> with-navigation2 -> Remove file name from image alt text and dictionary #25519) (5: image alt text)
  • please select the next word from dictionary and insert it to the list if you working on it

[tesseralis]

cc @muescha

[robintom]

Hi @tesseralis could you please assign this to me? I have been looking to do some open source contributions.

And I am somewhat confused on this issue, would you be able to provide more context for this?

[muescha]

@robintom since this issue is like an "umbrella" issue: the best is if you take only one small change at a time (for example put one package in code fences). this is more easy to approve a pull request.

anounce here which change you will do, so others can take an other one.

[FocalChord]

@muescha Hey I will be working on this issue. In particular this part:

• put filenames like .htaccess in code blocks

Should I open a PR for this particular part and then reference this issue?

See my PR below. Is that alright? (It is my first time contributing so let me know :))

[muescha]

@FocalChord great! - i updated the issue text

[FocalChord]

@muescha So for each other sub-issue do I make a seperate branch and then seperate PR?

Also when does the PR get merged in?

[muescha]

Hint: searching for text which is not already in code fences in files with RegEx (and File Mask *.md*)

[^`]some-thing[^`] 
[^`]\.htaccess[^`] // with dots

BTW: in WebStorm it shows you a section "Usage in comments" if the text is already in code blocks :)

[muescha]

yes - new branch and new PR

it takes some time to get merged, just be patient. the Gatsby team has to approve each PR and with smaller steps this is more easy to check :)

[FocalChord]

@muescha Awesome! Thanks for this :) I'll work on the 2nd, 3rd, 4th bulletpoints soon.

[meyian]

Hello @muescha and @FocalChord, I'm new here and I'd like to help. Since the list is being tackled one bullet point at a time, I was thinking I could start on bullet point no. 5.

some image alt text in tutorial pages are just file names (e.g. )

If I understand the task correctly, there are two parts to this:

• Delete "with-layout2" and other similar lines from dictionary.txt
• Go through the docs and give better alt text for those images

Do I have the right idea? But before then, is this even a ticket that's looking for help, or should I wait for the next one?

[tesseralis]

@meyian Yup! We'd want to add better alt text to the images in the tutorial.

[muescha]

i would suggest (for expample for type 1) a PR should only remove one line per dictionary (or like in #25339 similar ones) so PR are small scoped and approved fast.

[muescha]

somehow it not catches all places?

i run the lint for #25355 but in not catches for the NPM in:

gatsby/docs/blog/2018-05-24-launching-new-gatsby-company/index.md

Line 14 in 17ca485

- helps you leverage open source innovations in the React, NPM, and Gatsby communities for your web projects

gatsby/docs/blog/2018-05-24-launching-new-gatsby-company/index.md

Line 40 in 17ca485

### Backbone.js/Node.js/NPM

update: this is because the heading is marked as SourceNode, i think because of the slashes:

├─29 ParagraphNode
│   └─0 SentenceNode
│       └─0 SourceNode "Backbone.js/Node.js/NPM"

but this get catched:

gatsby/docs/blog/2018-05-24-launching-new-gatsby-company/index.md

Line 44 in 17ca485

Node.js, then only a couple of years old, was gaining traction fast. For the first time, NPM enabled the easy sharing of JavaScript libraries. Consequently, the number of libraries exploded. With a server runtime and ecosystem developing around JS, more and more web development tools started being written in JavaScript.

[gdstewart]

Hello! I wouldn't mind helping out too! I'd like to tackle 6 but I'm a bit confused about which imported components are being referred to, is it all imported components or only ones involving remark-mdx?

[ghost]

if I understand this correctly, for point 7 we need to edit the dictionary.txt and spilt the text characters from the numbers. Similarly for point 8, we need to split the words with dashes to separate individual words.
Can I work on this :)

[muescha]

7. try out if this working like this.

but:

6. it is a more general change to the system and i think the hardest one...

(edit: because Markdown parser hier in the comment changed the numbers from 6 to 8 if it is one line behind the seven)

[ghost]

okay, I'll start working on these.

[github-actions]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 60 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.
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! 💪💜

[muescha]

not stale

[pattimcletchie]

@muescha is this still open and needing to be worked on?

[mwlai288]

@muescha anything still needs to be worked on?

[muescha]

Yes. There are still more words from dictionary.txt which can be touched (fixed/removed)

[chrysillala]

Hi @muescha, is this still open? Can I try to help? Thanks

[prathyushasai]

Hi @muescha, Can I work on serverless and s3? Or are those already taken?

[muescha]

Feel free to grab words from dictionary

(But exclude blog posts from the /blog folder)

[brandonbawe]

I just started using gatsby and happy to know that it is open source and I must say gatsby is amazing. Please I'd like to work on this issue.

[kadhirash]

Hey @meganesu, does #27856 mean trying to work on this issue will be paused temporarily?

[LekoArts]

I think the biggest areas of problems were solved and the last couple of PRs weren't worthwhile/improving things a lot. Hence I'll close this one as there are better "good first issue" in our log.