ionic-team
diff --git a/‎.github/CODEOWNERS‎
Lines changed: 20 additions & 0 deletions b/‎.github/CODEOWNERS‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎.github/workflows/CI.yml‎
Lines changed: 6 additions & 5 deletions b/‎.github/workflows/CI.yml‎
Lines changed: 6 additions & 5 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 64 additions & 17 deletions b/‎CONTRIBUTING.md‎
Lines changed: 64 additions & 17 deletions
diff --git a/‎_templates/playground/new/angular.md.ejs.t‎
Lines changed: 2 additions & 2 deletions b/‎_templates/playground/new/angular.md.ejs.t‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎_templates/playground/new/angular_example_component_css.md.ejs.t‎
Lines changed: 2 additions & 2 deletions b/‎_templates/playground/new/angular_example_component_css.md.ejs.t‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎_templates/playground/new/angular_example_component_ts.md.ejs.t‎
Lines changed: 1 addition & 1 deletion b/‎_templates/playground/new/angular_example_component_ts.md.ejs.t‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎_templates/playground/new/demo.html.ejs.t‎
Lines changed: 5 additions & 5 deletions b/‎_templates/playground/new/demo.html.ejs.t‎
Lines changed: 5 additions & 5 deletions
diff --git a/‎_templates/playground/new/index.js‎
Lines changed: 75 additions & 52 deletions b/‎_templates/playground/new/index.js‎
Lines changed: 75 additions & 52 deletions
diff --git a/‎_templates/playground/new/index.md.ejs.t‎
Lines changed: 2 additions & 3 deletions b/‎_templates/playground/new/index.md.ejs.t‎
Lines changed: 2 additions & 3 deletions
@@ -0,0 +1,20 @@
+# Lines starting with '#' are comments.
+# Each line is a file pattern followed by one or more owners.
+
+# More details are here: https://help.github.com/articles/about-codeowners/
+
+# The '*' pattern is global owners.
+
+# Order is important. The last matching pattern has the most precedence.
+# The folders are ordered as follows:
+
+# In each subsection folders are ordered first by depth, then alphabetically.
+# This should make it easy to add new rules without breaking existing ones.
+
+/_templates/ @mapsandapps
+/docs/api/ @mapsandapps
+/src/ @mapsandapps
+/static/usage/ @mapsandapps
+
+/static/code/stackblitz/**/*/package.json @ionic-team/framework
+/static/code/stackblitz/**/*/package-lock.json @ionic-team/framework
@@ -8,11 +8,11 @@ on: [pull_request]
 
 jobs:
   test:
-    name: Test on node ${{ matrix.node_version }} and ${{ matrix.os }}
+    name: Test on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        node_version: [16]
+        node_version: [19]
         os: [windows-latest, macOS-latest]
 
     steps:
@@ -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
@@ -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.
 
@@ -1,7 +1,7 @@
 ---
 # this file's location depends on whether or not the css option or angular_ts option is selected via the prompt
-to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/${(css || angular_ts) ? 'angular/example_component_html.md' : 'angular.md'}` %>"
+to: "<%= `static/usage/v${version}/${name}/${path}/${(css || angular_ts) ? 'angular/example_component_html.md' : 'angular.md'}` %>"
 ---
 ```html
-<<%= name %>></<%= name %>>
+<<%= component %>></<%= component %>>
 ```
@@ -1,9 +1,9 @@
 ---
 # this file only gets generated if `css` (from the command line prompt) is true
-to: "<%= css ? `static/usage/v${version}/${name.replace('ion-', '')}/${path}/angular/example_component_css.md` : null %>"
+to: "<%= css ? `static/usage/v${version}/${name}/${path}/angular/example_component_css.md` : null %>"
 ---
 ```css
-<%= name %> {
+<%= component %> {
   /* styles go here */
 }
 ```
@@ -1,6 +1,6 @@
 ---
 # this file only gets generated if `angular_ts` (from the command line prompt) is true
-to: "<%= angular_ts ? `static/usage/v${version}/${name.replace('ion-', '')}/${path}/angular/example_component_ts.md` : null %>"
+to: "<%= angular_ts ? `static/usage/v${version}/${name}/${path}/angular/example_component_ts.md` : null %>"
 ---
 ```ts
 import { Component } from '@angular/core';
 
@@ -1,20 +1,20 @@
 ---
-arbitrary: <% nameWithoutIon = name.replace('ion-', ''); numberOfAncestors = (path.match(/\//g) || []).length; directoryChanges = '../'.repeat(numberOfAncestors) %>
-to: "<%= `static/usage/v${version}/${nameWithoutIon}/${path}/demo.html` %>"
+arbitrary: <% numberOfAncestors = (path.match(/\//g) || []).length; directoryChanges = '../'.repeat(numberOfAncestors) %>
+to: "<%= `static/usage/v${version}/${name}/${path}/demo.html` %>"
 ---
 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title><%= h.changeCase.titleCase(nameWithoutIon) %></title>
+    <title><%= h.changeCase.titleCase(name) %></title>
     <link rel="stylesheet" href="<%= directoryChanges %>../../../common.css" />
     <script src="<%= directoryChanges %>../../../common.js"></script>
     <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/dist/ionic/ionic.esm.js"></script>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/css/ionic.bundle.css" /><% if (css){ %>
 
     <style>
-      <%= name %> {
+      <%= component %> {
         /* styles go here */
       }
     </style><% } %>
@@ -24,7 +24,7 @@ to: "<%= `static/usage/v${version}/${nameWithoutIon}/${path}/demo.html` %>"
     <ion-app>
       <ion-content>
         <div class="container">
-          <<%= name %>></<%= name %>>
+          <<%= component %>></<%= component %>>
         </div>
       </ion-content>
     </ion-app>
 
@@ -5,60 +5,83 @@ const changeCase = require('change-case');
 //
 module.exports = {
   prompt: ({ inquirer }) => {
-    const questions = [
-      {
-        type: 'input',
-        name: 'name',
-        message: 'Which component is this playground for?',
-        initial: 'ion-button',
-        validate(value) {
-          return value.match(/^ion-[a-z/-]*[a-z]+$/) ? true : "Component name must be kebab-case and begin with 'ion-'";
+    return inquirer
+      .prompt([
+        {
+          type: 'toggle',
+          name: 'is_component',
+          message: 'Is this playground for a component?',
+          initial: true,
         },
-      },
-      {
-        type: 'input',
-        name: 'path',
-        message: 'What should the playground path be?',
-        hint: 'e.g. `basic` or `theming/colors`',
-        validate(value) {
-          return value.match(/^[a-z]+[a-z/-]*[a-z]+$/)
-            ? true
-            : "Path should begin and end with a letter and only contain lowercase letters, '-', or '/'";
-        },
-      },
-      {
-        type: 'select',
-        name: 'version',
-        message: 'Select the Ionic Framework version for the playground',
-        initial: '7',
-        choices: ['6', '7'],
-      },
-      {
-        type: 'toggle',
-        name: 'css',
-        message: 'Generate custom CSS files?',
-        enabled: 'Yes',
-        disabled: 'No',
-      },
-      {
-        type: 'toggle',
-        name: 'angular_ts',
-        message: 'Generate an Angular TypeScript file?',
-        enabled: 'Yes',
-        disabled: 'No',
-      },
-    ];
+      ])
+      .then((answers) => {
+        return inquirer
+          .prompt([
+            // ask a different question for components vs. other playgrounds
+            answers.is_component
+              ? {
+                  type: 'input',
+                  name: 'component',
+                  message: 'Which component is this playground for?',
+                  initial: 'ion-button',
+                  validate(value) {
+                    return value.match(/^ion-[a-z/-]*[a-z]+$/)
+                      ? true
+                      : "Component name must be kebab-case and begin with 'ion-'";
+                  },
+                }
+              : {
+                  type: 'input',
+                  name: 'name',
+                  message: 'Which guide section is this playground for?',
+                  initial: 'animations',
+                  validate(value) {
+                    return value.match(/^[a-z/-]+$/) ? true : 'Section must be kebab-case';
+                  },
+                },
+            {
+              type: 'input',
+              name: 'path',
+              message: 'What should the playground path be?',
+              hint: 'e.g. `basic` or `theming/colors`',
+              validate(value) {
+                return value.match(/^[a-z]+[a-z/-]*[a-z]+$/)
+                  ? true
+                  : "Path should begin and end with a letter and only contain lowercase letters, '-', or '/'";
+              },
+            },
+            {
+              type: 'select',
+              name: 'version',
+              message: 'Select the Ionic Framework version for the playground',
+              initial: '7',
+              choices: ['6', '7'],
+            },
+            {
+              type: 'toggle',
+              name: 'css',
+              message: 'Generate custom CSS files?',
+            },
+            {
+              type: 'toggle',
+              name: 'angular_ts',
+              message: 'Generate an Angular TypeScript file?',
+            },
+          ])
+          .then((answers) => {
+            answers.name = answers.name || answers.component.replace('ion-', '');
+
+            // if the playground is not for a component,
+            // include an ion-card in the playground
+            answers.component = answers.component || 'ion-card';
 
-    return inquirer.prompt(questions).then((answers) => {
-      const componentName = changeCase.pascal(answers.path.split('/').pop());
-      console.log(
-        `\nTo use this component in a docs markdown file, include\nthe following:\n\n## ${componentName}\n\nimport ${componentName} from '@site/static/usage/v7/${answers.name.replace(
-          'ion-',
-          ''
-        )}/${answers.path}/index.md';\n\n<${componentName} />\n`
-      );
+            const playgroundName = changeCase.pascal(answers.path.split('/').pop());
+            console.log(
+              `\nTo use this playground in a docs markdown file, include\nthe following:\n\n## ${playgroundName}\n\nimport ${playgroundName} from '@site/static/usage/v7/${answers.name}/${answers.path}/index.md';\n\n<${playgroundName} />\n`
+            );
 
-      return answers;
-    });
+            return answers;
+          });
+      });
   },
 };
@@ -1,6 +1,5 @@
 ---
-arbitrary: <% nameWithoutIon = name.replace('ion-', '') %>
-to: "<%= `static/usage/v${version}/${nameWithoutIon}/${path}/index.md` %>"
+to: "<%= `static/usage/v${version}/${name}/${path}/index.md` %>"
 ---
 import Playground from '@site/src/components/global/Playground';
 
@@ -56,5 +55,5 @@ import angular_example_component_css from './angular/example_component_css.md';
     angular,
 <% } -%>
   }}
-  src="usage/v<%= version %>/<%= nameWithoutIon %>/<%= path %>/demo.html"
+  src="usage/v<%= version %>/<%= name %>/<%= path %>/demo.html"
 />