Initial commit for docs

docs/.vitepress/config.mts

@@ -0,0 +1,112 @@
+import {defineConfig} from 'vitepress'
+import {tabsMarkdownPlugin} from 'vitepress-plugin-tabs'
+
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Inertia Rails",
+  description: "Community documentation for Inertia.js Rails adapter",
+
+  markdown: {
+    config(md) {
+      md.use(tabsMarkdownPlugin)
+    }
+  },
+
+  head: [
+    ['link', {rel: 'icon', href: '/favicon.ico', sizes: "32x32"}],
+    ['link', {rel: 'icon', href: '/icon.svg', type: 'image/svg+xml'}],
+  ],
+
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      {text: 'Home', link: '/'},
+      {text: 'Guide', link: '/guide'},
+      {
+        text: 'Links', items: [
+          {text: 'Official Inertia.js docs', link: 'https://inertiajs.com'},
+          {
+            text: 'Gems', items: [
+              {text: 'inertia_rails', link: 'https://github.com/inertiajs/inertia-rails'},
+              {text: 'inertia_rails-contrib', link: 'https://github.com/skryukov/inertia_rails-contrib'},
+            ]
+          },
+        ]
+      }
+    ],
+
+    logo: '/logo.svg',
+
+    sidebar: [
+      {
+        items: [
+          {text: 'Introduction', link: '/guide'},
+          {text: 'Demo app', link: '/guide/demo-application'},
+        ],
+      },
+      {
+        text: 'Installation',
+        items: [
+          {text: 'Server-side', link: '/guide/server-side-setup'},
+          {text: 'Client-side', link: '/guide/client-side-setup'},
+        ]
+      },
+      {
+        text: 'Core concepts',
+        items: [
+          {text: 'Who is it for', link: '/guide/who-is-it-for'},
+          {text: 'How it works', link: '/guide/how-it-works'},
+          {text: 'The protocol', link: '/guide/the-protocol'},
+        ]
+      },
+      {
+        text: 'The basics',
+        items: [
+          {text: 'Pages', link: '/guide/pages'},
+          {text: 'Responses', link: '/guide/responses'},
+          {text: 'Redirects', link: '/guide/redirects'},
+          {text: 'Routing', link: '/guide/routing'},
+          {text: 'Title & meta', link: '/guide/title-and-meta'},
+          {text: 'Links', link: '/guide/links'},
+          {text: 'Manual visits', link: '/guide/manual-visits'},
+          {text: 'Forms', link: '/guide/forms'},
+          {text: 'File uploads', link: '/guide/file-uploads'},
+          {text: 'Validation', link: '/guide/validation'},
+          {text: 'Shared data', link: '/guide/shared-data'},
+        ]
+      },
+      {
+        text: 'Advanced',
+        items: [
+          {text: 'Events', link: '/guide/events'},
+          {text: 'Testing', link: '/guide/testing'},
+          {text: 'Partial reloads', link: '/guide/partial-reloads'},
+          {text: 'Scroll management', link: '/guide/scroll-management'},
+          {text: 'Authentication', link: '/guide/authentication'},
+          {text: 'Authorization', link: '/guide/authorization'},
+          {text: 'CSRF protection', link: '/guide/csrf-protection'},
+          {text: 'Error handling', link: '/guide/error-handling'},
+          {text: 'Asset versioning', link: '/guide/asset-versioning'},
+          {text: 'Progress indicators', link: '/guide/progress-indicators'},
+          {text: 'Remembering state', link: '/guide/remembering-state'},
+          {text: 'Code splitting', link: '/guide/code-splitting'},
+          {text: 'Server-side rendering', link: '/guide/server-side-rendering'},
+        ]
+      }
+    ],
+
+    search: {
+      provider: 'local'
+    },
+
+    editLink: {
+      pattern: 'https://github.com/skryukov/inertia_rails-contrib/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    },
+
+    socialLinks: [
+      {icon: 'github', link: 'https://github.com/inertiajs/inertia-rails'}
+    ],
+  }
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,18 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+      enhanceAppWithTabs(app)
+  }
+} satisfies Theme

docs/.vitepress/theme/style.css

@@ -0,0 +1,163 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-purple-1);
+  --vp-c-brand-2: var(--vp-c-purple-2);
+  --vp-c-brand-3: var(--vp-c-purple-3);
+  --vp-c-brand-soft: var(--vp-c-purple-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+      0deg,
+      #9553e9,
+      #6d74ed
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+      -45deg,
+      #9553e9 50%,
+      #6d74ed 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+
+/**
+ * Component: Tabs
+ * -------------------------------------------------------------------------- */
+
+.plugin-tabs {
+  background-color: initial !important;
+}
+
+.plugin-tabs--tab-list {
+  background-color: var(--vp-code-block-bg);
+}
+
+.plugin-tabs--content {
+  padding: 0 !important;
+}
+
+.plugin-tabs--content div[class*='language-'] {
+  background-color: var(--vp-code-block-bg) !important;
+}
+
+.plugin-tabs--content div[class*='language-']:first-child {
+  border-top-left-radius: 0 !important;
+  border-top-right-radius: 0 !important;
+}

docs/guide/asset-versioning.md

@@ -0,0 +1,22 @@
+# Asset versioning
+
+One common challenge when building single-page apps is refreshing site assets when they've been changed. Thankfully, Inertia makes this easy by optionally tracking the current version of your site assets. When an asset changes, Inertia will automatically make a full page visit instead of a XHR visit on the next request.
+
+## Configuration
+
+To enable automatic asset refreshing, you need to tell Inertia the current version of your assets. This can be any arbitrary string (letters, numbers, or a file hash), as long as it changes when your assets have been updated.
+
+```ruby
+InertiaRails.configure do |config|
+  config.version = ViteRuby.digest # or any other versioning method
+end
+
+# You can also use lazy evaluation
+InertiaRails.configure do |config|
+  config.version = lambda { ViteRuby.digest }
+end
+```
+
+## Cache busting
+
+Asset refreshing in Inertia works on the assumption that a hard page visit will trigger your assets to reload. However, Inertia doesn't actually do anything to force this. Typically this is done with some form of cache busting. For example, appending a version query parameter to the end of your asset URLs.

docs/guide/authentication.md

@@ -0,0 +1,5 @@
+# Authentication
+
+One of the benefits of using Inertia is that you don't need a special authentication system such as OAuth to connect to your data provider (API). Also, since your data is provided via your controllers, and housed on the same domain as your JavaScript components, you don't have to worry about setting up CORS.
+
+Rather, when using Inertia, you can simply use whatever authentication system you like, such as solutions based on Rails' built-in `has_secure_password` method, or gems like [Devise](https://github.com/heartcombo/devise), [Sorcery](https://github.com/Sorcery/sorcery), [Authentication Zero](https://github.com/lazaronixon/authentication-zero), etc.

docs/guide/authorization.md

@@ -0,0 +1,28 @@
+# Authorization
+
+When using Inertia, authorization is best handled server-side in your application's authorization policies. However, you may be wondering how to perform checks against your authorization policies from within your Inertia page components since you won't have access to your framework's server-side helpers.
+
+The simplest approach to solving this problem is to pass the results of your authorization checks as props to your page components.
+
+Here's an example of how you might do this in a Rails controller using the [Action Policy](https://github.com/palkan/action_policy) gem:
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    render inertia: 'Users/Index', props: {
+      can: {
+        create_user: allowed_to?(:create, User)
+      },
+      users: User.all.map do |user|
+        user.as_json(
+          only: [:id, :first_name, :last_name, :email]
+        ).merge(
+          can: {
+            edit_user: allowed_to?(:edit, user)
+          }
+        )
+      end
+    }
+  end
+end
+```