chore(jp): merge recent update (#2883)

* docs(angular): supported angular versions (#2785)

* fix(playground): prevent horizontal scrollbar on ios device frame view (#2789)

* docs(toast): add version to layout (#2800)

* docs(toast): update cdn version (#2801)

* fix(playground): hidden iframes are hidden from screen readers (#2802)

* chore(version): update v5 and v6 docs to use the versioned docs demo deployment (#2796)

* docs(api): add accessibility section for icons (#2807)

* docs(layout): update css-utilities to show float properly (#2808)

closes #265

* fix(playground): iframe is hidden using display (#2809)

resolves #2778

* chore: clear docs/native directory when generating markdown (#2812)

* docs(segment): wrap text in labels for segments in toolbar playground (#2815)

* docs(security): clarify sanitizer (#2814)

* docs(gestures): remove browser support section (#2817)

* docs(icon): indicate where to find custom SVG usage (#2816)

* chore(): 翻訳ミスを修正

* updated

* build

* docs(datetime): clarify timezone usage (#2822)

* docs(animations): add type interfaces (#2811)

* docs(alert): alert input label is only for radio/checkbox (#2810)

* feat: docusaurus plugin to generate component api docs (#2797)

* Revert " feat: docusaurus plugin to generate component api docs (#2797)" (#2824)

This reverts commit cb056e9.

* docs(input, textarea): update migration guide for proper metadata usage (#2827)

* docs(slides): update migration guides to use Swiper 9 (#2833)

Co-authored-by: Liam DeBeasi <[email protected]>

* feat(translate): update translate

* feat(translate): add auto translation by DeepL

* feat(translate): h2 is translated

* feat(v7): translate api

* feat(translate): translate api

* feat(translate): translate api

* fix(api): fixed spelling

* feat(translation): partial retranslation

* chore(): remove unused file

* docs(modal): clarify swipeToClose migration (#2839)

* docs(select): fix typeahead search (#2840)

Co-authored-by: BlackHakwDC <[email protected]>

* docs(updating): clean up verbiage and broken links on migration guides (#2842)

* fix(translate): proofread the translation of DeepL

* chore(translate): run translate

* feat(translate): translate searchbar

* feat(translate): fix deepl translation

* fix(translate): translate docs/index

* docs(badge): content must be passed to be shown (#2844)

* docs(config): move framework config guides to unified config guide (#2727)

* docs(live reload): update docs about Capacitor programmatic builds (#2843)

Resolves #2805

* docs(many): update config links (#2846)

* docs(config): add documentation for innerHTMLTemplatesEnabled (#2826)

* docs: update dev workflow instructions (#2848)

* docs(react, vue): add vite pwa docs (#2841)

* docs(v5): change CDN links to use core@v5 (#2847)

* docs(quickstart): update to include imports and match current starter (#2849)

resolves #2485

---------

Co-authored-by: Liam DeBeasi <[email protected]>

* docs(input, textarea): clarify error text behavior (#2853)

* docs(native): fix grammar and typos (#2806)

* docs: rxjs migration guide for v7 (#2852)

* docs(modal): playground example to prevent swipe to dismiss (#2820)

* docs(react): update imports for swiper migration (#2851)

* docs(slides): fix typo in Angular migration guide (#2856)

* docs(toast): remove hardware back button dismissal (#2854)

Co-authored-by: liamdebeasi <[email protected]>

* feat(translate): remove '自動翻訳' from cache data

* docs(lifecycle): clarify when lifecycles are called (#2858)

* docs(config): update innerHTMLTemplatesEnabled default (#2857)

* feat: docusaurus plugin to generate component api docs (#2829)

* chore: remove v7 beta banner (#2836)

* docs(config): update v7 to latest version (#2862)

* chore(many): update v7 playgrounds to point to Ionic 7.0.0 (#2859)

* fix(plugin): account for versions with no paths (#2865)

* fix(config): fall back to label (#2866)

* docs(upgrade-pill): link to v7 upgrade guide (#2724)

* chore(): remove unused auto translated

* docs(support): update support table for v7 (#2868)

resolves #2867

* docs(datetime): remove unused variable from example (#2803)

* docs(v7): update breaking changes link (#2869)

* docs(v7): update migration guide tags (#2870)

* feat(translate): translate api

* docs(migration): fix header levels in v4 migration guide (#2872)

* docs(migration): update versioned migration guide to link to latest version of page (#2871)

Co-authored-by: skofgar <[email protected]>

* chore(docs contributing): update code of conduct to link out to full … (#2875)

* chore(i18n): remove production check for Japanese docs (#2825)

* docs(deployment): typo with windows requirements (#2879)

* chore(coc email): update email to devrel (#2881)

* fix(path): fix language path

* Revert "fix(path): fix language path"

This reverts commit 0d070be.

* fix(lang): default path change to be en(if Japanese

* feat(api): update api translate

* fix(jp): set the v7 document version to v7 (#2884)

* docs(select): popover can be used with multiple prop (#2887)

* Revert "fix(jp): set the v7 document version to v7 (#2884)" (#2889)

This reverts commit c4004b5.

* docs(react): add example for useIonRouter (#2888)

* docs(modal): controller playground uses bolded action (#2890)

* docs(theming): update vendor prefixed line height (#2661)

* docs(layout): update structure docs to use new playground examples (#2882)

resolves #594

* docs(theming): remove stray whitespace (#2895)

* docs(CONTRIBUTING): update misspell and period addition (#2893)

* fix(modal): controller playground uses v7 label syntax (#2891)

* fix(styles): add sidebar indentation for nested sections (#2886)

* fix(styles): add sidebar indentation for nested sections

* fix: spacing at end of sidebar

* fix: spacing between sections

* fix: padding between collapsed sections

* docs(router-link): removal of phone demo on v6 and v7 (#2899)

* docs(studio): removal of studio pages for v7, v6, and v5 (#2900)

* docs(native): correctly show all the native plugins (#2903)

* docs(nav): clearly state that it's not used for routing (#2901)

* fix(ColorGenerator): always prepend entered colors with pound sign (#2904)

* docs(item): migrate inputs example to v7 (#2835)

* docs(vue): update quickstart steps to remove typescript (#2689)

* docs(modal): playground for auto height sheets (#2905)

* docs(react): clarify state behavior with Ionic React (#2894)

Co-authored-by: Liam DeBeasi <[email protected]>

* docs(quickstart): remove unnecessary references to React Native (#2238)

* Update quickstart.md

this was set as intro to React Native which is wrong in my opinion. Should be Ionic React instead.

* Remove other incorrect references to React Native

---------

Co-authored-by: Shawn Taylor <[email protected]>

* docs(searchbar): debounce uses ionInput (#2913)

Co-authored-by: guillaumesmo <[email protected]>

* docs(react): remove old overview and update link (#2897)

Resolves #2220

* docs(react): update pwa-elements import

* styles(): Add developer experts cta section to intro/next page (#2908)

* fix(developer experts card): Add dark mode compatability (#2919)

* docs(react): provide unique key instead of index (#2630)

As providing index as keys is a bad practice, this commit modifies the key value to be `photo.filepath` which will be unique and consistent while adding new photos.

[Keys - react docs](https://reactjs.org/docs/lists-and-keys.html#keys)
[example why it is not recommended](https://robinpokorny.com/blog/index-as-a-key-is-an-anti-pattern/)

* docs(toast): clarify aria-live usage (#2914)

* docs(security): clarify IonicSafeString usage with innerHTMLTemplatesEnabled (#2906)

* docs(cli): update Ionic CLI docs for version 7 (#2924)

* docs(pwa): update firebase instructions for deploying pwa (#2916)

* docs(react): update firebase instructions for deploying pwa

---------

Co-authored-by: Brett Peary <[email protected]>

* docs(support): remove migration guide link (#2925)

This link does not exist anymore as the migration guides are available as a top-level category in the sidebar.

* fix(release-notes): remove element symbols and names and update design (#2921)

* docs(angular): add missing non-null assertion operator (#2683)

* fix(): page components file structure (#2907)

* docs(your-first-app): mark webviewPath as optional in UserPhoto interface (#2926)

Co-authored-by: derf974 <[email protected]>

* fix(angular-getting-started): type errors (#2688)

Co-authored-by: Greg Billetdeaux <[email protected]>
Co-authored-by: Maria Hutt <[email protected]>

* Revert "fix(): page components file structure (#2907)" (#2928)

This reverts commit d848669.

* refactor(api): v5 docs use internal import (#2929)

* fix(playground): allow automatic mode selection when relevant base file is overwritten (#2922)

* fix: styles for ion-slides migration (#2930)

* refactor(playground): remove unused angularModuleOptions feature (#2933)

* docs(ionicslides): include slides param link (#2934)

Co-authored-by: Arno <[email protected]>

* docs(tab): remove references to using Stencil with tab (#2932)

* chore(crowdin): api docs are no longer ignored (#2938)

* fix(docsdemo, playground): add keys to list items (#2940)

* fix(ColorAccordion, LayeredColorsSelect): add keys to list items (#2942)

* fix(docdemo, coloraccordion): correctly format SVG/CSS props (#2941)

* chore(contributing): remove slack link on v5 (#2939)

* docs(Swiper): fix typo in slidesPerView value (#2945)

* docs(android): update where to find SDK/AVD managers (#2947)

Co-authored-by: rtpHarry <[email protected]>

* chore(intro/next): Elite Ionic -> Ionic Start (#2931)

* docs(developing): tip for changing node_modules permissions (#2950)

Co-authored-by: Utku Demir <[email protected]>

* docs(breadcrumbs): update vue example (#2949)

* docs(lifecycle): clarify method descriptions (#2951)

Co-authored-by: BAYiTUPAi <[email protected]>

* docs(updating): add angular toolkit upgrade to v7 upgrade guide (#2952)

* chore(lint): add prettier and lint on CI (#2946)

- Adds prettier to a lint command (prettier was installed just not used anywhere)
- Runs `npm install` & `npm lint` on CI
- Updates the `.prettierignore` to be more up-to-date with the current docs structure 
  - `static/code/stackblitz` files were ignored because it was modifying the indentation surrounding `{ TEMPLATE }` and this caused the StackBlitz to look worse when opened
- Adds `mdx` as a parser to the `@ionic/prettier-config` and updates this repo to use that version

* docs(support): update angular support policy (#2953)

This PR updates the support table to note that Angular 16 is supported for Ionic v7

* docs(range): update docs to use label prop (#2955)

* fix(tabs): correct router playground src (#2957)

* docs(app-store): add reference to App Store Connect (#2198)

Co-authored-by: Brandy Carney <[email protected]>

* docs(developing): update Java instructions to mention JDK 11 for latest cordova-android (#2200)

Updates the developing android documentation to reflect the latest Cordova guide here: https://cordova.apache.org/docs/en/11.x/guide/platforms/android/#java-development-kit-jdk

---------

Co-authored-by: Brandy Carney <[email protected]>

* docs(react): remove IonContent from tabs example (#2958)

* docs(vue): remove IonContent from tabs example (#2959)

* docs(dark-mode): replace deprecated addListener() usage (#1908)

Co-authored-by: Maria Hutt <[email protected]>

* docs(quickstart): remove typescript for imports and tests (#2216)

* Update quickstart.md

Currently, the "use Javascript" section is incomplete as Jest is still configured to use Typescript and running `npm run test:unit` will throw errors. The section was revised to to include Jest Javascript configuration changes.

---------

Co-authored-by: Shawn Taylor <[email protected]>

* fix(CodeColor, LayeredColorsSelect): fix invalid DOM nesting (#2963)

* docs(react): remove unopened closing tag (#2964)

* fix: Ionic CLI links to latest docs page (#2961)

* docs(tabs): angular usage does not use explicit ion-router-outlet (#2965)

Co-authored-by: skytern <[email protected]>

* doc(CORS): update the native options (#2954)

Include different options for Capacitor and Cordova (legacy).
Also fixes what was a dead link to Ionic Native.

* feat(playground): inline dependencies per framework example (#2970)

* chore: update minor release to happen every 4 weeks if needed (#2972)

* docs(select): add label slot and aria label playgrounds (#2971)

* docs(vue): add community guide by theafolayan (#1795)

Co-authored-by: Maria Hutt <[email protected]>

* docs(PWAs): add Vue to list of PWA deployment guides (#2974)

Co-authored-by: VAS000 <[email protected]>

* docs(spinner): add docs for resizing (#2966)

* docs(spinner): add docs for resizing

* docs(developing): update default Android SDK path (#2771)

Co-authored-by: Brandy Carney <[email protected]>

* docs(native): fix typo (#2976)

* chore: prettier formatting (#2979)

* chore: prettier formatting

* chore: revert invalid changes

* docs(angular): relative routing is supported (#2980)

Co-authored-by: rdlabo<[email protected]>>

* docs(angular): update component testing code snippets (#2985)

* chore(deps): update react and vue playground dependencies (#2989)

* docs(datetime): add playground for styling wheel pickers (#2982)

* docs(angular):updated component photo service (#2986) (#2987)

* docs(angular):updated component photo service (#2986)

* docs(angular):changed component photo service (#2986)

changed photo.path --> photo.path!

* remove extra newline

---------

Co-authored-by: Amanda Johnston <[email protected]>

* docs(android): clarify steps to set up native project and run with Capacitor (#1889)

Co-authored-by: Shawn Taylor <[email protected]>

* docs(security): content security policies (#2975)


Co-authored-by: Liam DeBeasi <[email protected]>

* chore(fundamentals): clarify events (#2992)

* docs(app-store): add release flag (#2990)

Co-authored-by: zhangshengjie <[email protected]>

* docs(vue): fix lifecycle table formatting (#2967)

Adds a new line before the table to allow the markdown to render properly

* docs(infinite-scroll): use the correct custom event (#2995)

* docs(angular): fix indentation in 5-adding-mobile.md (#2855)

* docs: fix indentation in 5-adding-mobile.md

* Also change in v7 docs

---------

Co-authored-by: Shawn Taylor <[email protected]>

* docs(input): add label slot and no visible label demos (#2997)

* docs(select): add playgrounds for toggle icon customization (#2996)

* add playgrounds

* lint

* Update static/usage/v7/select/customization/custom-toggle-icons/index.md

Co-authored-by: Liam DeBeasi <[email protected]>

* Update static/usage/v7/select/customization/icon-flip-behavior/index.md

Co-authored-by: Liam DeBeasi <[email protected]>

* fix icon usage for React and Vue

* rename toggleIconWhenOpen to expandedIcon

---------

Co-authored-by: Liam DeBeasi <[email protected]>

* docs(input): input masking examples (#2993)

* docs(textarea): add label slot examples (#3001)

* chore: add playgrounds for JP docs (#3004)

* chore: upgrade maskito dependencies to v1 (#3005)

* fix(playground-tabs): show arrows on long list (#3009)

* docs(native): improve grammar

fixed wording mistakes

* docs(your-first-app): switch to Date.now() (#2915)

Co-authored-by: Maria Hutt <[email protected]>

* docs(list): use dark mode aware color (#3015)

Co-authored-by: reslear <[email protected]>

* docs(maskito): update credit card mask format (#3007)

* chore(ci): check for diff after running prettier (#2981)

* chore: lint content (#3020)

* docs(animation): add playground for override example (#3018)

Co-authored-by: dillionmegida <[email protected]>

* docs(vue): Improve documentation for removing Typescript steps in v7 (#3002)

* feat(playground): add support for generating a new playground (#2994)

* Add prompts and generate vue file

* Generate other files

* Use variables in headers

* Add readme

* Add prompt with option to generate css files

* Add version to prompt and modify files accordingly

* Update readme

* Address PR review

* Add hint for component name casing

* Add Angular TS option

* Reformat to use advanced prompting

* Refactor where markdown output comes from

* Remove default value for path; add validation

* Add validation for component name

---------

Co-authored-by: Amanda Johnston <[email protected]>

* chore: enable renovate for component playground deps (#3016)

* Configure Renovate (#3017)

* Add renovate.json

* chore: remove invalid setting

---------

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Sean Perkins <[email protected]>

* docs(modal): clarify swipe to close section (#3021)

* docs(react): clarify IonTabs behavior with IonPage (#3012)

* chore(renovate): remove extending docs config (#3027)

* docs(animation): add playground for group example (#3025)

* docs(animations): add playground for chained animations (#3026)

Co-authored-by: dillionmegida <[email protected]>

* chore(deps): update dependency vite to v2.9.16 [security] (#3028)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

* docs(animation): add playground for basic animations (#3031)

Co-authored-by: dillionmegida <[email protected]>

* fix(deps): update dependency @types/node to v16.18.38 (#3033)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

* fix(generation): correct angular imports (#3034)

* Refactor: Improve readability

* Combine index files and fix bug with angular ts generation

* docs(animations): buttons in StackBlitz demos do not need id (#3037)

* chore(renovate): limit include paths (#3030)

* chore(renovate): limit include paths

* fix: use matchPackagePatterns

* docs(animations): add playground for before and after hooks (#3035)

Co-authored-by: dillionmegida <[email protected]>

* docs(animations): add playground for preference based (#3036)

Co-authored-by: dillionmegida <[email protected]>

* docs(angular): add type assertion for your first app code snippet (#2910)

Was getting an error: "Type 'string | undefined' is not assignable to type 'string'." Adding an exclamation point at the end of line 111 solves it.

* docs(animation): add playground example for double-click gesture  (#3042)

Co-authored-by: dillionmegida < [email protected]>

Co-authored-by: Maria Hutt <[email protected]>

* docs(animation): add gesture animation playground (#3043)

Co-authored-by: dillionmegida <[email protected]>

* docs(gesture): add playground example for basic usage (#3038)

Co-authored-by: dillionmegida <[email protected]>

* docs(animation): add playground example for keyframes (#3039)

Co-authored-by: dillionmegida < [email protected]>

* docs(item-sliding): clarify expandable behavior (#3044)

* docs(menu): add playgrounds for menu sides and multiple menus (#3049)

* fix(): fix conflict package.json

* chore(): fixed lint

* fix(ci): fix lint and diff

* fix(script): follow new docs script

* translate

* chore

* chore(): fix confrect

* fmt

* fix(): remove i18n folder from git

---------

Co-authored-by: Sean Perkins <[email protected]>
Co-authored-by: Amanda Johnston <[email protected]>
Co-authored-by: Liam DeBeasi <[email protected]>
Co-authored-by: Brandy Carney <[email protected]>
Co-authored-by: BlackHakwDC <[email protected]>
Co-authored-by: Maria Hutt <[email protected]>
Co-authored-by: Shawn Taylor <[email protected]>
Co-authored-by: ptmkenny <[email protected]>
Co-authored-by: reslear <[email protected]>
Co-authored-by: skofgar <[email protected]>
Co-authored-by: John Wheeler <[email protected]>
Co-authored-by: Robert G <[email protected]>
Co-authored-by: Serhii Kulykov <[email protected]>
Co-authored-by: Yusuf Sahin HAMZA <[email protected]>
Co-authored-by: FernetB <[email protected]>
Co-authored-by: Ashraf Latif <[email protected]>
Co-authored-by: guillaumesmo <[email protected]>
Co-authored-by: James McDonald <[email protected]>
Co-authored-by: jaredcbaum <[email protected]>
Co-authored-by: Thejas Kiran P S <[email protected]>
Co-authored-by: Matt Netkow <[email protected]>
Co-authored-by: Brett Peary <[email protected]>
Co-authored-by: Daniel Feliz <[email protected]>
Co-authored-by: derf974 <[email protected]>
Co-authored-by: gregbilletdeaux <[email protected]>
Co-authored-by: Greg Billetdeaux <[email protected]>
Co-authored-by: Maria Hutt <[email protected]>
Co-authored-by: Arno <[email protected]>
Co-authored-by: rtpHarry <[email protected]>
Co-authored-by: Utku Demir <[email protected]>
Co-authored-by: BAYiTUPAi <[email protected]>
Co-authored-by: Joost Jansen <[email protected]>
Co-authored-by: Brandy Carney <[email protected]>
Co-authored-by: Austine A <[email protected]>
Co-authored-by: Stephan Schmitz <[email protected]>
Co-authored-by: praxxys <[email protected]>
Co-authored-by: Zakuru San <[email protected]>
Co-authored-by: skytern <[email protected]>
Co-authored-by: Ken Sodemann <[email protected]>
Co-authored-by: Oluwaseun Raphael Afolayan <[email protected]>
Co-authored-by: VAS000 <[email protected]>
Co-authored-by: Julien De Coster <[email protected]>
Co-authored-by: Martijn Grendelman <[email protected]>
Co-authored-by: Chandra Nandan <[email protected]>
Co-authored-by: Sanjeed <[email protected]>
Co-authored-by: zhangshengjie <[email protected]>
Co-authored-by: Kevin Cunningham <[email protected]>
Co-authored-by: Bobby Galli <[email protected]>
Co-authored-by: Stefan Kempinger <[email protected]>
Co-authored-by: Biskweet <[email protected]>
Co-authored-by: reslear <[email protected]>
Co-authored-by: dillionmegida <[email protected]>
Co-authored-by: Simo Mafuxwana <[email protected]>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: dillionmegida <[email protected]>
Co-authored-by: Joshua Albrechtsen <[email protected]>

.github/workflows/CI.yml

@@ -0,0 +1,33 @@
+# GitHub Actions docs
+# https://help.github.com/en/articles/about-github-actions
+# https://help.github.com/en/articles/workflow-syntax-for-github-actions
+
+name: Install Dependencies, Lint
+
+on: [pull_request]
+
+jobs:
+  test:
+    name: Test on node ${{ matrix.node_version }} and ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node_version: [16]
+        os: [windows-latest, macOS-latest]
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node_version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node_version }}
+    - name: Install Dependencies
+      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: Check Diff
+      run: git diff --exit-code
+      shell: bash

.prettierignore

@@ -1,13 +1,15 @@
 src/theme/DocItem
 src/theme/DocPage
 legacy-stencil-components
-node_modules
 scripts/bak
-src/styles.bak
-src/pages
+
 docs/api
 docs/native
 docs/cli/commands
 
+static/code/stackblitz
+
 .docusaurus
-.github
+.github
+build
+node_modules

CONTRIBUTING.md

@@ -54,8 +54,9 @@ Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The c
     - `components/` - styles split out into the components they target
 - `static/`
   - `demos/` - self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter
+  - `usage/` - playgrounds that can be created by running `npm run playground:new` [(docs)](_templates/README.md#new-playground-template)
 - `versioned_docs/` - versions of the docs created by the docusaurus versioning command
-- `versioned_sitebars/` - versions of the docs sidebars created by the docusaurus versioning command
+- `versioned_sidebars/` - versions of the docs sidebars created by the docusaurus versioning command
 
 ## Authoring Content
 
@@ -84,7 +85,7 @@ The Ionic docs have been translated into Japanese and are in the process of bein
 
 We use Crowdin for our translation service. You can participate in the translation effort on the [Ionic Crowdin page](https://crowdin.com/project/ionic-docs).
 
-_Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo_
+_Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo._
 
 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).
 

_templates/README.md

@@ -0,0 +1,32 @@
+# Hygen templates
+
+The templates in this directory are intended to be used with [hygen](https://www.hygen.io/) to generate boilerplate files. Check out [the root package.json](../package.json) to see if there are any custom commands to use them (e.g. `npm run playground:new`). You can also run e.g. `hygen playground new` to use a generator.
+
+Some helpful docs links for updating/creating templates:
+
+- [enquirer](https://github.com/enquirer/enquirer#toggle-prompt) for building command line prompts
+- [inflection](https://www.hygen.io/docs/templates#helpers-and-inflections) and [change case](https://www.hygen.io/docs/templates#change-case-helpers) for e.g. changing the case of variables submitted via the prompts
+
+# New playground template
+
+## Generation
+
+To create a new playground, run `npm run playground:new`. This will walk you through some prompts to decide what files for the generator to create for the playground, and what their paths should be.
+
+The path defaults to `basic`. If there is already a basic playground, you'll want to input a different path for the playground.
+
+The CSS option will add extra files if you need to include custom CSS in your playground.
+
+If you need a component for multiple versions of Ionic Framework, you (currently) need to run the generator once for each version.
+
+## Usage
+
+Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.md](../docs/api/button.md)) by doing something similar to the following example:
+
+```
+## Feature
+
+import Feature from '@site/static/usage/v7/button/feature/index.md';
+
+<Feature />
+```

_templates/playground/new/angular.md.ejs.t

@@ -0,0 +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'}` %>"
+---
+```html
+<<%= name %>></<%= name %>>
+```

_templates/playground/new/angular_example_component_css.md.ejs.t

@@ -0,0 +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 %>"
+---
+```css
+<%= name %> {
+  /* styles go here */
+}
+```

_templates/playground/new/angular_example_component_ts.md.ejs.t

@@ -0,0 +1,17 @@
+---
+# 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 %>"
+---
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+<% if (css){ -%>
+  styleUrls: ['./example.component.css'],
+<% } -%>
+})
+export class ExampleComponent {
+}
+```

_templates/playground/new/demo.html.ejs.t

@@ -0,0 +1,32 @@
+---
+arbitrary: <% nameWithoutIon = name.replace('ion-', ''); numberOfAncestors = (path.match(/\//g) || []).length; directoryChanges = '../'.repeat(numberOfAncestors) %>
+to: "<%= `static/usage/v${version}/${nameWithoutIon}/${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>
+    <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 %> {
+        /* styles go here */
+      }
+    </style><% } %>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <<%= name %>></<%= name %>>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>

_templates/playground/new/index.js

@@ -0,0 +1,64 @@
+const changeCase = require('change-case');
+
+// see types of prompts:
+// https://github.com/enquirer/enquirer/tree/master/examples
+//
+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-'";
+        },
+      },
+      {
+        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',
+      },
+    ];
+
+    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`
+      );
+
+      return answers;
+    });
+  },
+};

_templates/playground/new/index.md.ejs.t

@@ -0,0 +1,60 @@
+---
+arbitrary: <% nameWithoutIon = name.replace('ion-', '') %>
+to: "<%= `static/usage/v${version}/${nameWithoutIon}/${path}/index.md` %>"
+---
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+<% if (css){ %>
+import react_main_tsx from './react/main_tsx.md';
+import react_main_css from './react/main_css.md';
+
+<% } else { -%>
+import react from './react.md';
+<% } -%>
+import vue from './vue.md';
+<% if (css || angular_ts){ %>
+import angular_example_component_html from './angular/example_component_html.md';
+<% } else { -%>
+import angular from './angular.md';
+<% } -%>
+<% if (angular_ts){ -%>
+import angular_example_component_ts from './angular/example_component_ts.md';
+<% } -%>
+<% if (css){ -%>
+import angular_example_component_css from './angular/example_component_css.md';
+<% } -%>
+
+<Playground
+  version="<%= version %>"
+  code={{
+    javascript,
+<% if (css){ -%>
+    react: {
+      files: {
+        'src/main.tsx': react_main_tsx,
+        'src/main.css': react_main_css,
+      },
+    },
+<% } else { -%>
+    react,
+<% } -%>
+    vue,
+<% if (angular_ts || css){ -%>
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+<% if (angular_ts){ -%>
+        'src/app/example.component.ts': angular_example_component_ts,
+<% } -%>
+<% if (css){ -%>
+        'src/app/example.component.css': angular_example_component_css,
+<% } -%>
+      },
+    },
+<% } else { -%>
+    angular,
+<% } -%>
+  }}
+  src="usage/v<%= version %>/<%= nameWithoutIon %>/<%= path %>/demo.html"
+/>

_templates/playground/new/javascript.md.ejs.t

@@ -0,0 +1,14 @@
+---
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/javascript.md` %>"
+---
+```html
+<<%= name %>></<%= name %>>
+<% if (css){ -%>
+
+<style>
+  <%= name %> {
+    /* styles go here */
+  }
+</style>
+<% } -%>
+```

_templates/playground/new/react.md.ejs.t

@@ -0,0 +1,19 @@
+---
+arbitrary: <% pascalName = h.changeCase.pascal(name) %>
+# this file's location depends on whether or not the css option is selected via the prompt
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/${css ? 'react/main_tsx.md' : 'react.md'}` %>"
+---
+```tsx
+import React from 'react';
+import { <%= pascalName %> } from '@ionic/react';<% if (css){ %>
+
+import './main.css';<% } %>
+
+function Example() {
+  return (
+    <<%= pascalName %>></<%= pascalName %>>
+  );
+}
+export default Example;
+```
+

_templates/playground/new/react_main_css.md.ejs.t

@@ -0,0 +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}/react/main_css.md` : null %>"
+---
+```css
+<%= name %> {
+  /* styles go here */
+}
+```

_templates/playground/new/vue.md.ejs.t

@@ -0,0 +1,28 @@
+---
+arbitrary: <% pascalName = h.changeCase.pascal(name) %>
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/vue.md` %>"
+---
+```html
+<template>
+  <<%= name %>></<%= name %>>
+</template>
+
+<script lang="ts">
+  import { <%= pascalName %> } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: {
+      <%= pascalName %>,
+    },
+  });
+</script>
+<% if (css){ -%>
+
+<style scoped>
+  <%= name %> {
+    /* styles go here */
+  }
+</style>
+<% } -%>
+```

crowdin.yml

@@ -8,6 +8,5 @@ files:
   - source: /docs/**/*
     translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
     ignore:
-      - /docs/api/**/*
       - /docs/cli/commands/**/*
       - /docs/native/**/*