docs: add additional information to the documentation

docs/content/1.index.md → docs/content/0.index.md

@@ -8,7 +8,7 @@ layout: page
 ---
 cta:
   - Get Started
-  - /getting-started
+  - /get-started/introduction
 secondary:
   - Open on GitHub →
   - https://github.com/nuxt-modules/ionic

docs/content/1.get-started/1.introduction.md

@@ -0,0 +1,55 @@
+---
+navigation.icon: uil:info-circle
+description: 'Batteries-included, zero-config needed, Ionic integration for Nuxt'
+---
+
+# Introduction
+
+::alert{type="warning"}
+⚠️ @nuxtjs/ionic is currently a work in progress. ⚠️
+::
+
+`@nuxtjs/ionic` provides a batteries-included, zero-config needed, Ionic integration for Nuxt.
+
+Supercharge your Ionic apps with the power of Nuxt, giving you the tremendous development experience you're used to
+when using Nuxt for web.
+
+Follow the installation guide to get going immediately, or continue reading to find out more about what this module provides.
+
+::alert{type="info"}
+Get started with our [Installation guide](/get-started/installation).
+::
+
+## What is Ionic?
+
+[The Ionic SDK](https://ionicframework.com/) is an open-source UI toolkit for building modern, cross-platform mobile apps from a single codebase. It deeply integrates with Vue for a delightful mobile dev experience.
+
+::alert{type="info"}
+Read the [Ionic documentation for Vue](https://ionicframework.com/docs/vue/overview) to learn more about Vue development with Ionic.
+::
+
+## Features
+
+This module attempts to get you going with Nuxt + Ionic quickly, providing sane defaults for ionic and helpful components and utilities. The configuration file can still customize and override its default behaviors and provide full customisation of ionic.
+
+::list{type=success}
+- **Ionic router integration:** continue defining routes based on the structure of your `~/pages` directory and using page-level utilities such as `definePageMeta()`.
+- **Auto-imports**: Ionic components, composables and icons are all [auto-imported](https://nuxt.com/docs/guide/concepts/auto-imports) for ease of use.
+- **Helpful components and utilities**: This module provides components and utilities to accomplish common tasks more easily.
+- **PWA support**: out-of-the-box support for progressive web apps, using `nuxt-pwa-module`.
+- **Pre-render routes**
+- **Mobile meta tags**
+- **Capacitor integration**: works out-of-the-box with [Capacitor](https://capacitorjs.com/) for shipping to native platforms like iOS and Android.
+::
+
+::alert{type="info"}
+Read more about [our features](/overview).
+::
+
+## Cookbook
+
+Our cookbook documentation provides common use-cases with code examples to get you going as fast as possible. And if you create something useful, come back and submit a PR to have it added to our cookbook.
+
+::alert{type="info"}
+Discover common recipes in [our cookbook](/cookbook).
+::

docs/content/1.get-started/2.installation.md

@@ -0,0 +1,80 @@
+---
+navigation.icon: uil:play-circle
+description: 'Get started with the ionic module for Nuxt'
+---
+
+# Installation
+
+Get started quickly by installing and setting up this module with the following instructions.
+
+## Prerequisites
+
+- A fresh or existing Nuxt project
+- [Nuxt's prerequisites](https://nuxt.com/docs/getting-started/installation#prerequisites)
+- [Ionic's environment setup](https://ionicframework.com/docs/intro/environment)
+- [Capacitor's enviroment setup](https://capacitorjs.com/docs/getting-started/environment-setup) if using iOS or Android
+
+## Installation
+
+Add `@nuxtjs/ionic` to your project's dev dependencies:
+
+::code-group
+
+```bash [yarn]
+yarn add --dev @nuxtjs/ionic
+```
+
+```bash [npm]
+npm install @nuxtjs/ionic -D
+```
+
+```bash [pnpm]
+pnpm install @nuxtjs/ionic -D
+```
+
+::
+
+### Nuxt Module
+
+Next, add the module to your Nuxt configuration in `nuxt.config.ts`.
+
+```js{}[nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/ionic'],
+  ssr: false,
+})
+```
+
+::alert{type="warning"}
+If deploying to iOS or Android, be aware the app must be able to run completely client-side. We recommend setting `ssr: false` in your nuxt config. Find out more in [deploying to both web and device](/cookbook/web-and-device).
+::
+
+Finally, either remove your `app.vue` file or [replace it with a custom one](/cookbook/customising-app-vue).
+
+### Development Server
+
+Now you'll be able to start your Nuxt app in development mode as usual:
+
+::code-group
+
+```bash [yarn]
+yarn dev -o
+```
+
+```bash [npm]
+npm run dev -- -o
+```
+
+```bash [pnpm]
+pnpm dev -o
+```
+
+::
+
+::alert{type=success icon=✨ .font-bold}
+Well done! A browser window should automatically open for <http://localhost:3000>.
+::
+
+::alert{type=info}
+The first time you start a Nuxt project with `@nuxtjs/ionic` enabled, a `ionic.config.json` file will be created if it doesn't already exist.
+::

docs/content/1.get-started/3.configuration.md

@@ -0,0 +1,116 @@
+---
+navigation.icon: uil:wrench
+---
+
+# Configuration
+
+This module provides configuration options for itself, as well as passing through configuration for ionic.
+
+Configuration for capacitor is set in the usual way, via capacitor.config.ts.
+
+### Module Config
+
+This module exposes three keys for configuration: `integrations`, `css` and `config`:
+
+```js [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/ionic'],
+  ionic: {
+    integrations: {
+      //
+    },
+    css: {
+      //
+    },
+    config: {
+      //
+    }
+  },
+})
+```
+
+#### `integrations`
+
+Integrations control which other modules this module should enable and setup from the list below. Disabling them allows you to remove them, or gives you the option to set them up yourself.
+
+- **meta**
+
+  Default: `true`  
+  Disable to take full control of meta tags.
+
+- **pwa**
+
+  Default: `true`  
+  Disable to take full control of icon generation, manifest and service worker installation.
+
+- **router**
+
+  Default: `true`  
+  Disable to configure Ionic Router yourself.
+
+- **icons**
+
+  Default: `true`  
+  Disable to stop icons from being auto-imported.
+
+#### `css`
+
+Configure which Ionic stylesheets are automatically added to your application. For more information about
+these stylesheets, [see the Ionic Documentation for Stylesheets](https://ionicframework.com/docs/layout/global-stylesheets).
+
+- **core**
+
+  Default: `true`  
+  Disable to import these CSS files manually:
+
+  - `@ionic/vue/css/core.css`
+
+- **basic**
+
+  Default: `true`  
+  Disable to import these CSS files manually:
+
+  - `@ionic/vue/css/normalize.css`
+  - `@ionic/vue/css/structure.css`
+  - `@ionic/vue/css/typography.css`
+
+- **utilities**
+
+  Default: `false`  
+  Enable to add extra Ionic CSS utilities:
+
+  - `@ionic/vue/css/padding.css`
+  - `@ionic/vue/css/float-elements.css`
+  - `@ionic/vue/css/text-alignment.css`
+  - `@ionic/vue/css/text-transformation.css`
+  - `@ionic/vue/css/flex-utils.css`
+  - `@ionic/vue/css/display.css`
+
+#### `config`
+
+Configure Ionic components globally across your app, such as app mode, tab button layout, etc. For example:
+
+```js [nuxt.config.ts]
+export default defineNuxtConfig({
+  ionic: {
+    config: {
+      rippleEffect: false,
+      mode: 'md',
+      // ...
+    },
+  },
+})
+```
+
+::alert{type="info"}
+Please see the [Ionic Config Options](https://ionicframework.com/docs/vue/config#config-options) for available keys, values
+and examples of how they work.
+::
+
+### Capacitor Config
+
+Capacitor is configured via the `capacitor.config.ts` file - this is only required if you are targeting native devices such as iOS or Android.
+
+::alert{type="info"}
+Please see the [Capacitor Config docs](https://capacitorjs.com/docs/config) for more information.
+::

docs/content/1.get-started/4.enabling-capacitor.md

@@ -0,0 +1,70 @@
+---
+navigation.icon: nonicons:capacitor-16
+---
+
+# Enabling Capacitor
+
+[Capacitor](https://capacitorjs.com/) is a powerful tool for shipping to native platforms like iOS and Android, separate from or alongside your web app.
+
+The good news is that it's installed by default with `@nuxtjs/ionic`. You just need to enable it in your ionic app, and choose what platforms you want to support.
+
+> The Ionic CLI is available via `npx` or can be installed globally with `npm install -g @ionic/cli` or `yarn global add @ionic/cli` or `pnpm add -g @ionic/cli`.
+
+::code-group
+
+```bash [npx]
+npx @ionic/cli integrations enable capacitor
+npx @ionic/cli capacitor add ios
+npx @ionic/cli capacitor add android
+```
+
+```bash [npm]
+# ionic config set -g npmClient npm
+
+ionic integrations enable capacitor
+ionic capacitor add ios
+ionic capacitor add android
+```
+
+```bash [yarn]
+ionic config set -g npmClient yarn
+
+ionic integrations enable capacitor
+ionic capacitor add ios
+ionic capacitor add android
+```
+
+```bash [pnpm]
+ionic config set -g npmClient pnpm
+
+ionic integrations enable capacitor
+ionic capacitor add ios
+ionic capacitor add android
+```
+
+::
+
+::alert{type="info"}
+Read more about [creating for iOS and Android here](/cookbook/creating-ios-android-apps).
+::
+
+#### Run on iOS or Android
+
+Once an Android or iOS project is added with Capacitor, you can run your app on an iOS or Android emulator.
+
+::alert
+Android Studio and SDK (for Android projects) or XCode (for iOS projects) are required to use the `npx cap open` or `npx cap run` command. See the [Capacitor Environment Setup docs](https://capacitorjs.com/docs/getting-started/environment-setup) for details.
+::
+
+To build, sync, and run your app:
+
+1. Create a web build with `npx nuxi generate` or `npx nuxi build`.
+2. Run `npx cap sync` to update your Capacitor project directories with your latest app build.
+3. Run `npx cap run android` or `npx cap run ios` to run the app from the command line using an installed device **OR**
+4. _(Optional)_ Run `npx cap open android` or `npx cap open ios` to open the project in Android Studio or XCode, respectively.
+
+> Remember to run `npx cap sync` after every new build to ensure your Android and/or iOS project is up-to-date.
+
+::alert{type="info"}
+Read more about [local development for iOS and Android here](/cookbook/local-development).
+::