Gatsby: 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 #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:

  • [x] .babelrc (@FocalChord in #25585) (1: file names)
  • [x] .env and more file extensions (@tesseralis in #25665)
  • [x] .htaccess (@FocalChord in #25321) (1: file names)
  • [x] .yml (@FocalChord in #25584) (1: file names)
  • [x] allfile-query (@meyian in #26022) (5: image alt text)
  • [x] ASKGatsbyJS (@muescha in #26297) (4: brand names)
  • [x] Codepen -> CodePen (@muescha in #25875) (4: brand names)
  • [x] Codepen -> CodePen (@muescha in #25875) (4: brand names)
  • [x] excited-gif (@meyian in #26304) (5: image alt text)
  • [x] filesystem-query (@meyian in #26022) (5: image alt text)
  • [x] Graphiql & GraphiQl(@tesseralis in #25664) (4: brand names)
  • [x] graphql (@FocalChord in #25586|@muescha in #25626) (4: brand names)
  • [x] graphiql-filesystem (@meyian in #26022) (5: image alt text)
  • [x] infer* (@FocalChord in #25339) (2: code)
  • [x] markdown-autocomplete (@meyian in #25841) (5: image alt text)
  • [x] npm + *NPM enforce npm in small letters (@muescha in #25355) (4: brand names)
  • [x] poject fix word (@muescha in #25844)
  • [x] *Webpack + *Webpacks enforce webpack in small letters (@muescha in #25681) (4: brand names)
  • [x] with-layout2 (@meyian in #25358) (5: image alt text)
  • [x] with-navigation2 (@meyian in #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:
https://github.com/gatsbyjs/gatsby/blob/17ca4854d12228d93257f88ab66f2642cf5f01b0/docs/blog/2018-05-24-launching-new-gatsby-company/index.md#L14

https://github.com/gatsbyjs/gatsby/blob/17ca4854d12228d93257f88ab66f2642cf5f01b0/docs/blog/2018-05-24-launching-new-gatsby-company/index.md#L40

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:
https://github.com/gatsbyjs/gatsby/blob/17ca4854d12228d93257f88ab66f2642cf5f01b0/docs/blog/2018-05-24-launching-new-gatsby-company/index.md#L44

[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?

[kapil-raj]

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]

1. try out if this working like this.

but:

1. 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)

[kapil-raj]

okay, I'll start working on these.

[muescha]

an other bug:

the spell checker not reach the table content - for example i forbid *AgilityCMS in dictionary, but it not found it in a title in a table cell:

https://github.com/gatsbyjs/gatsby/blob/5ad9582fa174c75c4ea67daf3e4e312c464a3421/docs/docs/headless-cms.md#L45

[muescha]

ok - it seems that a table cell is never checked because of:
https://github.com/syntax-tree/mdast-util-to-nlcst/blob/a05338c5aa287885cfa473b4099d51ca42629c64/index.js#L10

var ignore = ['table', 'tableRow', 'tableCell']

i will investigate how it can be done ....

[muescha]

suggested solution:

Maybe using remark-rehype and then rehype-retext is better?

i get it done, will file a PR in next days...

[FocalChord]

@muescha I have done a few more issues above :)

[muescha]

@FocalChord thanks a lot :)

[meyian]

Hello, I had two questions:

@muescha I realize you renamed my pull request. Is getting the right format for pull requests something I can learn?

Then, I pushed some changes to docs/tutorial/part-three/index.md and the build failed, because

warning `uncentered` is misspelt; did you mean `uncensored`? uncentered retext-spell

Would the fix for this be as simple as adding the word "uncentered" to dictionary.txt? Or how else should I address this?

[muescha]

PR Title

there are some recommendations for PR titles:

https://www.gatsbyjs.org/contributing/managing-pull-requests/#commit-and-pr-title

i unified a little bit the titles of related PRs of this issue to make it more easy to identify them for the review team.

Uncentered

yes i see it is a new unknown word which you added to the PR, if you are sure that is not a spelling error (like in this case) and not a file name/function name/variable name/package name (put them in code fences) then you can add it to the dictionary.txt.

[marcysutton]

I added uncentered to the dictionary as discussed above to keep that PR moving, and it's merged now. Is there anything else left to do on this issue, or can we close it?

[muescha]

@marcysutton there are much more entries to clean up in the dictionary.txt, i only placed "current activities to the umbrella issue, because there are 2194 lines in dictionary to check...

[Hina-softwareEngineer]

Hi, I am a beginner and want to contribute here. I am confused. Can someone guide me?

[muescha]

@Hina-softwareEngineer you are welcome

Overview

you can start with the docs about contributing and the section Repo Setup

contribution to this issue

• for this issue you look for only one entry in the dictionary.txt
• remove this wrong entry or fix this one entry.
• then run the yarn script lint:docs and see where there are the problems and then fix it (see also Docs Contributions)

@gatsbyjs/learning did i forget an instruction?

[meyian]

I just created a PR which removed several words at once, because the first word "allfile-query" appeared in two docs files. In cleaning up the alt text of these files, they had three other wrong dictionary.txt words in common, so I thought it made the most sense to clean up both these files at once and remove any words from dictionary.txt that no longer exist in the docs after this cleanup. I hope I had the right idea, but feel free to let me know if this PR needs splitting up.

@tesseralis: I wanted to edit the Current Activities section in the main comment above and add the new words I was working on, but I wasn't sure if having a PR opened means I check the box next to my entry, or that's only for if the work has been merged in. How does it work?

(Edit: Also, in my PR, I used the "official" camelCase spelling of the word allFile, and now that the linter has run, it's complaining about allFile not being "allfile". What would be the ideal situation in this case. Should I rename allFile to allfile, or would a new dictionary entry be needed to handle the camelCase spelling?)

[muescha]

very good!

yes you can edit it :)

• an empty checkbox means it is not merged.
• checked entries are merged into the repo

(i just followed the other "Umbrella" Issues (like [Umbrella] TypeScript Migration (Help wanted!) #21995), but to list all dictionary entries here for claiming a word would be a little to much...)

[muescha]

allFile

• i see are all the allFile in your PR are code fences

i tested:

• this is a "bug" or a feature? - in descriptions the code fences are not recognized and thats why they are not ecluded from checking :/
• but i think it is a feature, because the alt text can not "enhanced" by markdown stuff (in the github preview of the file the code fences are removed from the image alt text)

[muescha]

i would suggest to reword the descriptions so that code fences are not needed
/cc @tesseralis what you suggest?

[meyian]

@muescha Okay, no problem. I reworded the alt texts to remove the code fences and the references to "allFile".

[meyian]

With PR #26304, all the incorrect alt texts in dictionary.txt have been replaced, I believe. I used the regex !\[.*-.*\]\(.*\) to search through the repo for all kebab-case filenames in alt texts, and all the entries that appeared in dictionary.txt have been removed in the various PRs.

[github-actions[bot]]

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! 💪💜

[github-actions[bot]]

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.