chore(): add cspell and fix spelling errors in docs (#3069)

ionic-team · Sep 25, 2023 · 60dccd9 · 60dccd9 · vercel · Sep 25, 2023
1 parent 2256722
commit 60dccd9
Show file tree

Hide file tree

Showing 74 changed files with 2,381 additions and 385 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -25,9 +25,10 @@ jobs:
       run: npm ci --legacy-peer-deps
     - name: Lint
       run: npm run lint
-    # Lint changes should be pushed
-    # to the branch before the branch
-    # is merge eligible.
+    - name: Spell Check
+      run: npm run spellcheck
+    # Lint and spell check changes should be pushed
+    # to the branch before the branch is merge eligible.
     - name: Check Diff
       run: git diff --exit-code
       shell: bash
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,6 +4,9 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check
 
 - [Contributing Guide](#contributing-guide)
   - [Development Workflow](#development-workflow)
+    - [Previewing Changes](#previewing-changes)
+    - [Linting Documentation](#linting-documentation)
+    - [Spell Check](#spell-check)
   - [Using VS Code on Windows](#using-vs-code-on-windows)
   - [Project Structure](#project-structure)
     - [Directories](#directories)
@@ -12,22 +15,77 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check
   - [Translation](#translation)
   - [Reporting Issues](#reporting-issues)
   - [Pull Request Guidelines](#pull-request-guidelines)
-  <!-- - [Project Management](#project-management) -->
   - [Deploying](#deploying)
   - [License](#license)
 
 ---
 
 ## Development Workflow
 
+### Previewing Changes
+
 In order to run the documentation locally, install the dependencies and run the development server:
 
 ```sh
 $ npm install --legacy-peer-deps
 $ npm start
 ```
 
-> **Note**: certain versions of npm (5-8) and Node.js (10-16) are required to run certain scripts.
+> [!NOTE]
+> Certain versions of npm (5-8) and Node.js (10-16) are required to run certain scripts.
+
+### Linting Documentation
+
+This repository uses [Prettier](https://prettier.io/), an opinionated code formatter, in order to keep consistent formatting throughout the documentation. Run the following command to automatically fix all formatting, and then push any changes:
+
+```
+npm run lint
+```
+
+### Spell Check
+
+This repository uses [cspell](https://cspell.org/), a spell checker for code, to automatically flag any spelling errors. Run the following command to see any spelling errors:
+
+```
+npm run spellcheck
+```
+
+> [!NOTE]
+> Any spelling errors will need to be fixed manually. There are various ways to ignore words or sections that were flagged erroneously. These are listed below.
+
+#### Ignoring words
+
+**To ignore:**
+
+- A **specific word**, add it to the following file: `cspell-wordlist.txt`
+  - For example, `Ionicons` is flagged as an unknown word. Since this is the name of our software, it has been added to this file to be ignored.
+- A **directory** or anything matching a **regular expression**, update the following file: `cspell.json`
+  - For example, we don't want to flag anything inside of code ticks (<code>`</code>) or code blocks (<code>```</code>), so there are regular expressions added to ignore anything inside of these.
+- An **entire line**, add the following comment above it:
+  ```markdown
+  <!-- cspell:disable-next-line -->
+  ```
+- **Multiple lines**, add comments above and below the lines to be ignored:
+
+  ```markdown
+  <!-- cspell:disable -->
+
+  <p>Everything inside of these comments will be ignored by the spell checkr. Proofread your own words carefully.</p>
+
+  <!-- cspell:enable -->
+  ```
+
+> [!IMPORTANT]
+> You need to have line breaks between the `cspell` comments and any HTML elements,
+> otherwise the build will error with `Module build failed`.
+
+#### Tips
+
+Before adding a word or section to be ignored, see if there is a way to make it pass the spell check. Technical terms that are part of an API may need to be wrapped in code formatting. For example, the word `keydown` is flagged as an unknown word by the spell checker, but this is a [Web API event](https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event). We can wrap any mentions of `keydown` in two backticks (<code>\`keydown\`</code>) in order to avoid it being flagged by the spell checker.
+
+Comments disabling the next line or entire sections of documentation are useful for making the spell checker ignore people's names.
+
+In general, we should try to avoid ignoring words unless they are technical terms that are used throughout the documentation and wouldn't necessarily make sense formatted as code.
 
 ---
 
@@ -87,6 +145,8 @@ We use Crowdin for our translation service. You can participate in the translati
 
 _Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo._
 
+<!-- cspell:disable-next-line -->
+
 The Japanese translation of the docs were built by an independent team, lead by [rdlabo](https://github.com/rdlabo) and can be found and contributed to on the [ionic-jp group's `ionic-docs` project page](https://github.com/ionic-jp/ionic-docs).
 
 ## Reporting Issues
@@ -100,7 +160,8 @@ If the issue you're reporting is a bug, please be sure it is an issue with the I
 - OS and browser versions
 - If possible, a demo repo or CodePen/CodeSandbox
 
-> **Note**: Some [reference content](#reference-content) is pulled from other Ionic repos. In that case, please submit your issue on the docs repo with a link to the repo where the content lives.
+> [!NOTE]
+> Some [reference content](#reference-content) is pulled from other Ionic repos. In that case, please submit your issue on the docs repo with a link to the repo where the content lives.
 
 ---
 
@@ -110,20 +171,6 @@ When submitting pull requests, please keep the scope of your change contained to
 
 ---
 
-<!-- ## Project Management
-
-Internally, the Ionic documentation team uses a [project board](https://github.com/ionic-team/ionic-docs/projects/3) to plan work on the docs. The lanes on the board are:
-
-- **Backlog** :file_cabinet: - Issues we plan to address, generally sorted by urgency
-- **On Deck** :baseball: - Issues to be addressed during the current sprint, pulled from backlog during sprint planning
-- **In Progress** :hammer: - Assigned issues that are currently being addressed
-- **Needs Review** :mag: - Pull requests and issues that have a pending review
-- **Done** :tada: - Issues that have been resolved
-
-If you're looking for issues to help out with, we'd recommend either asking about an issue in the backlog or checking for issues labeled [`help-wanted`](https://github.com/ionic-team/ionic-docs/labels/help%20wanted).
-
---- -->
-
 ## Deploying
 
 The Ionic documentation's `main` branch is deployed automatically and separately from the [Ionic site](https://github.com/ionic-team/ionic-site) itself. The Ionic site then uses a proxy for paths under `/docs` to request the deployed documentation.

diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt
@@ -0,0 +1,80 @@
+Appflow
+Codepen
+Firestore
+Genymotion
+Hygen
+Ionicon
+Ionicons
+Logcat
+Maskito
+Pluralsight
+Swiper
+Udemy
+Vetur
+Wistia
+
+actionsheet
+fabs
+datetime
+datetimes
+datetimepicker
+infinitescroll
+searchbar
+searchbars
+sidemenu
+textarea
+textareas
+
+appstore
+authed
+autogrow
+automations
+autoplay
+comparewith
+composables
+engageable
+flexbox
+frontmatter
+fullscreen
+geolocation
+interactives
+isopen
+jank
+janky
+jarsigner
+jsdelivr
+keyframes
+keytool
+lifecycles
+localstorage
+mobileweb
+phablet
+playstore
+preconfigured
+preflighted
+proxying
+quickstart
+retargeted
+runtimes
+scroller
+subcomponent
+subcomponents
+swipeable
+templating
+transpiling
+treeshaking
+triaging
+typeahead
+unminified
+unsanitized
+viewports
+webapps
+webviews
+xlarge
+xsmall
+
+allowtransparency
+mozallowfullscreen
+msallowfullscreen
+oallowfullscreen
+webkitallowfullscreen
diff --git a/cspell.json b/cspell.json
@@ -0,0 +1,25 @@
+{
+  "dictionaries": ["custom-words"],
+  "dictionaryDefinitions": [
+    {
+      "name": "custom-words",
+      "path": "./cspell-wordlist.txt",
+      "addWords": true
+    }
+  ],
+  "ignoreRegExpList": [
+    "/(```+)[\\s\\S]+?\\1/g",
+    "`([^`]*)`",
+    "/:[a-zA-Z0-9-_\\+]+:/g"
+  ],
+  "ignorePaths": [
+    "docs/cli",
+    "docs/native",
+    "versioned_docs/**/api",
+    "versioned_docs/**/cli",
+    "versioned_docs/**/native"
+  ],
+  "flagWords": [
+    "hte"
+  ]
+}
diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@ The `/docs` folder houses all markdown files. The page structure loosely maps to
 
 ## Versioning
 
-This folder can also contain components, assets, and whatever else is meant to be versioned when the docusaurus versioning script is run. For example, if there is a page component that is only relevant to the `layout` section in the current version of Ionic, it could be added to a `_components/` folder in `docs/layout/`. When the versioning script is run, the component will be copied to `versioned_docs/verion-{X}/layout/_components/` and there will now be a separate component in `docs/layout/_components/` that can be deleted or updated to the latest version. The same concept applies to images and other files.
+This folder can also contain components, assets, and whatever else is meant to be versioned when the docusaurus versioning script is run. For example, if there is a page component that is only relevant to the `layout` section in the current version of Ionic, it could be added to a `_components/` folder in `docs/layout/`. When the versioning script is run, the component will be copied to `versioned_docs/version-{X}/layout/_components/` and there will now be a separate component in `docs/layout/_components/` that can be deleted or updated to the latest version. The same concept applies to images and other files.
 
 If components are meant to be shared across versions, they can be put in `src/components/`. If images and other served files are meant to be shared across versions they can be put in `static/`.
 

diff --git a/docs/angular/performance.md b/docs/angular/performance.md
@@ -56,6 +56,8 @@ For more information on how Angular manages change propagation with `ngFor` see
 
 ## From the Community
 
+<!-- cspell:disable -->
+
 [High Performance Animations in Ionic](https://www.joshmorony.com/high-performance-animations-in-ionic/) - Josh Morony
 
 [High Performance List Filtering in Ionic](https://www.joshmorony.com/high-performance-list-filtering-in-ionic-2/) - Josh Morony
@@ -64,6 +66,8 @@ For more information on how Angular manages change propagation with `ngFor` see
 
 [Ionic Framework is Fast (But Your Code Might Not Be)](https://www.joshmorony.com/ionic-framework-is-fast-but-your-code-might-not-be/) - Josh Morony
 
+<!-- cspell:enable -->
+
 :::note
 Do you have a guide you'd like to share? Click the _Edit this page_ button below.
 :::
diff --git a/docs/angular/slides.md b/docs/angular/slides.md
@@ -224,24 +224,24 @@ To migrate, we would change the name of the event to `slidechange`:
 
 Below is a full list of event name changes when going from `ion-slides` to Swiper Angular:
 
-| ion-slides Event        | Swiper Event               |
-| ----------------------- | -------------------------- |
-| ionSlideWillChange      | slidechangetransitionstart |
-| ionSlideDidChange       | slidechangetransitionend   |
-| ionSlideDoubleTap       | doubletap                  |
-| ionSlideDrag            | slidermove                 |
-| ionSlideNextStart       | slidenexttransitionstart   |
-| ionSlideNextEnd         | slidenexttransitionend     |
-| ionSlidePrevStart       | slideprevtransitionstart   |
-| ionSlidePrevEnd         | slideprevtransitionend     |
-| ionSlideReachStart      | reachbeginning             |
-| ionSlideReachEnd        | reachend                   |
-| ionSlideTap             | tap                        |
-| ionSlideTouchStart      | touchstart                 |
-| ionSlideTouchEnd        | touchend                   |
-| ionSlideTransitionStart | transitionstart            |
-| ionSlideTransitionEnd   | transitionend              |
-| ionSlidesDidLoad        | init                       |
+| ion-slides Event          | Swiper Event                 |
+| ------------------------- | ---------------------------- |
+| `ionSlideWillChange`      | `slidechangetransitionstart` |
+| `ionSlideDidChange`       | `slidechangetransitionend`   |
+| `ionSlideDoubleTap`       | `doubletap`                  |
+| `ionSlideDrag`            | `slidermove`                 |
+| `ionSlideNextStart`       | `slidenexttransitionstart`   |
+| `ionSlideNextEnd`         | `slidenexttransitionend`     |
+| `ionSlidePrevStart`       | `slideprevtransitionstart`   |
+| `ionSlidePrevEnd`         | `slideprevtransitionend`     |
+| `ionSlideReachStart`      | `reachbeginning`             |
+| `ionSlideReachEnd`        | `reachend`                   |
+| `ionSlideTap`             | `tap`                        |
+| `ionSlideTouchStart`      | `touchstart`                 |
+| `ionSlideTouchEnd`        | `touchend`                   |
+| `ionSlideTransitionStart` | `transitionstart`            |
+| `ionSlideTransitionEnd`   | `transitionend`              |
+| `ionSlidesDidLoad`        | `init`                       |
 
 :::note
 All events available in Swiper Element can be found at <a href="https://swiperjs.com/swiper-api#events" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#events</a>.
@@ -281,19 +281,19 @@ export class SlidesExample {
 
 Below is a full list of method changes when going from `ion-slides` to Swiper Element:
 
-| ion-slides Method  | Notes                                                                                |
-| ------------------ | ------------------------------------------------------------------------------------ |
-| getActiveIndex()   | Use the `activeIndex` property instead.                                              |
-| getPreviousIndex() | Use the `previousIndex` property instead.                                            |
-| getSwiper()        | Get a reference to the Swiper instance using the `swiper` prop. See example above.   |
-| isBeginning()      | Use the `isBeginning` property instead.                                              |
-| isEnd()            | Use the `isEnd` property instead.                                                    |
-| length()           | Use the `slides` property instead. (i.e swiper.slides.length)                        |
-| lockSwipeToNext()  | Use the `allowSlidesNext` property instead.                                          |
-| lockSwipeToPrev()  | Use the `allowSlidePrev` property instead.                                           |
-| lockSwipes()       | Use the `allowSlideNext`, `allowSlidePrev`, and `allowTouchMove` properties instead. |
-| startAutoplay()    | Use the `autoplay` property instead.                                                 |
-| stopAutoplay()     | Use the `autoplay` property instead.                                                 |
+| ion-slides Method    | Notes                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| `getActiveIndex()`   | Use the `activeIndex` property instead.                                              |
+| `getPreviousIndex()` | Use the `previousIndex` property instead.                                            |
+| `getSwiper()`        | Get a reference to the Swiper instance using the `swiper` prop. See example above.   |
+| `isBeginning()`      | Use the `isBeginning` property instead.                                              |
+| `isEnd()`            | Use the `isEnd` property instead.                                                    |
+| `length()`           | Use the `slides` property instead. (i.e swiper.slides.length)                        |
+| `lockSwipeToNext()`  | Use the `allowSlidesNext` property instead.                                          |
+| `lockSwipeToPrev()`  | Use the `allowSlidePrev` property instead.                                           |
+| `lockSwipes()`       | Use the `allowSlideNext`, `allowSlidePrev`, and `allowTouchMove` properties instead. |
+| `startAutoplay()`    | Use the `autoplay` property instead.                                                 |
+| `stopAutoplay()`     | Use the `autoplay` property instead.                                                 |
 
 :::note
 All methods and properties available on the Swiper instance can be found at <a href="https://swiperjs.com/swiper-api#methods-and-properties" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#methods-and-properties</a>.

diff --git a/docs/angular/testing.md b/docs/angular/testing.md
@@ -293,7 +293,7 @@ When an `@ionic/angular` application is generated, a default end-to-end test app
 
 - `protractor.conf.js` - the Protractor configuration file
 - `tsconfig.e2e.json` - specific TypeScript configuration for the testing application
-- `src/app.po.ts` - a page object containing methods that navigate the application, query elements in the DOM, and maninpulate elements on the page
+- `src/app.po.ts` - a page object containing methods that navigate the application, query elements in the DOM, and manipulate elements on the page
 - `src/app.e2e-spec.ts` - a testing script
 
 #### Page Objects

diff --git a/docs/angular/your-first-app/8-distribute.md b/docs/angular/your-first-app/8-distribute.md
@@ -18,7 +18,7 @@ For more on connecting your code repository to Appflow, checkout the [Connect yo
 
 The Appflow SDK (also known as Ionic Deploy plugin) will allow you to take advantage of arguably two of the best Appflow features: deploying live updates to your app and bypassing the app stores. Ionic Appflow's Live Update feature is shipped with Appflow SDK and features the capabilities of detecting and syncing the updates for your app that you have pushed to your identified channels within the dashboard.
 
-To get the Appflow SDK plugin added to your project, you can follow the install instructions within the Appflow Dashboard by clicking on "Install Instructions" inside of the `Deploy > Destinations` section. Alternatively, you can install the plugin manually by excuting the following command in your app's root directory:
+To get the Appflow SDK plugin added to your project, you can follow the install instructions within the Appflow Dashboard by clicking on "Install Instructions" inside of the `Deploy > Destinations` section. Alternatively, you can install the plugin manually by executing the following command in your app's root directory:
 
 ```shell
 ionic deploy add  \
@@ -75,7 +75,7 @@ For more information, visit the [Create an Automation](https://ionic.io/docs/app
 
 ## Create an Environment
 
-[Package builds](https://ionic.io/docs/appflow/package/builds) and [Deploy builds](https://ionic.io/docs/appflow/deploy/builds) can be futher customized via [Environments](https://ionic.io/docs/appflow/automation/environments). This powerful feature allows you to create different configurations based on the environment variables passed in at build time. When combined with the [Automation](https://ionic.io/docs/appflow/automation/intro) feature, development teams can easily configure development, staging, and production build configurations, allowing them to embrace DevOps best practices and ship better quality updates faster than ever.
+[Package builds](https://ionic.io/docs/appflow/package/builds) and [Deploy builds](https://ionic.io/docs/appflow/deploy/builds) can be further customized via [Environments](https://ionic.io/docs/appflow/automation/environments). This powerful feature allows you to create different configurations based on the environment variables passed in at build time. When combined with the [Automation](https://ionic.io/docs/appflow/automation/intro) feature, development teams can easily configure development, staging, and production build configurations, allowing them to embrace DevOps best practices and ship better quality updates faster than ever.
 
 Creating an Environment is available for those on our [Basic plans](https://ionic.io/pricing) and above. More information on this can be found in the [Create an Environment](https://ionic.io/docs/appflow/quickstart/environment) section within the Appflow docs.