add docs page to cancancan using vitepress

.gitignore

@@ -13,3 +13,6 @@ Gemfile.lock
 .ruby-version
 .ruby-gemset
 /tmp
+docs/.vitepress/cache
+node_modules
+docs/.vitepress/dist

docs/.vitepress/config.mts

@@ -0,0 +1,85 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "CanCanCan",
+  description: "The authorization Gem for Ruby on Rails.",
+  head: [
+    ['link', { rel: "apple-touch-icon", sizes: "180x180", href: "/apple-touch-icon.png" }],
+    ['link', { rel: "icon", type: "image/png", sizes: "32x32", href: "/favicon-32x32.png" }],
+    ['link', { rel: "icon", type: "image/png", sizes: "16x16", href: "/favicon-16x16.png" }],
+    ['link', { rel: "mask-icon", href: "./safari-pinned-tab.svg", color: "#3c3ebf" }],
+    ['link', { rel: "manifest", href: "/manifest.json" }],
+
+    ['link', { rel: "icon", href: "/favicon.ico", type: "image/x-icon" }],
+    ['link', { rel: "shortcut icon", href: "/favicon.ico", type: "image/x-icon" }],
+  ],
+  sitemap: {
+    hostname: 'https://cancancan.com'
+  },
+  cleanUrls: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Docs', link: '/README' },
+    ],
+    externalLinkIcon: true,
+
+    lastUpdated: {
+      formatOptions: {
+        dateStyle: 'medium',
+      }
+    },
+    editLink: {
+      pattern: 'https://github.com/CanCanCommunity/cancancan/edit/main/docs/:path'
+    },
+    search: {
+      provider: 'local'
+    },
+
+    logo: '/cancancan.png',
+
+    sidebar: [
+      {
+        text: 'Summary',
+        items: [
+          { text: 'Introduction', link: '/introduction' },
+          { text: 'Installation', link: '/installation' },
+          { text: 'Define and check abilities', link: '/define_check_abilities' },
+          { text: 'Controller helpers', link: '/controller_helpers' },
+          { text: 'Fetching records', link: '/fetching_records' },
+          { text: 'Cannot', link: '/cannot' },
+          { text: 'Hash of conditions', link: '/hash_of_conditions' },
+          { text: 'Combine Abilities', link: '/combine_abilities' },
+          { text: 'Check abilities - avoid mistakes', link: '/check_abilities_mistakes' },
+          { text: 'Handling CanCan::AccessDenied', link: '/handling_access_denied' },
+          { text: 'Customize controller helpers', link: '/changing_defaults' },
+          { text: 'Accessing request data', link: '/accessing_request_data' },
+          { text: 'SQL strategies', link: '/sql_strategies' },
+          { text: 'Accessible attributes', link: '/accessible_attributes' },
+          { text: 'Testing', link: '/testing' },
+          { text: 'Internationalization', link: '/internationalization' }
+        ]
+      },
+      {
+        text: 'Further topics',
+        items: [
+          { text: 'Migrating', link: '/migrating' },
+          { text: 'Debugging Abilities', link: '/debugging' },
+          { text: 'Split your ability file', link: '/split_ability' },
+          { text: 'Define Abilities - best practices', link: '/define_abilities_best_practices' },
+          { text: 'Abilities in database', link: '/abilities_in_database' },
+          { text: 'Role-based Authorization', link: '/role_based_authorization' },
+          { text: 'Model Adapter', link: '/model_adapter' },
+          { text: 'Rules compression', link: '/rules_compression' },
+          { text: 'Inherited Resources', link: '/inherited_resources' },
+          { text: 'Devise', link: '/devise' },
+          { text: 'FriendlyId', link: '/friendly_id' }
+        ]
+      }
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
+    ]
+  }
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,16 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+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 }) {
+  }
+} satisfies Theme

docs/.vitepress/theme/style.css

@@ -0,0 +1,139 @@
+/**
+ * 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-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-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(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  /* --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 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;
+}
+

docs/check_abilities_mistakes.md

@@ -14,7 +14,7 @@ cannot? :destroy, @article
 
 What we want to explain you in this chapter is that you can also pass the class instead of a single instance:
 
-```rhtml
+```erb
 <% if can? :create, Project %>
   <%= link_to "New Project", new_project_path %>
 <% end %>

docs/index.md

@@ -0,0 +1,66 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: CanCanCan
+  text: Developer guide
+  tagline: The authorization Gem for Ruby on Rails.
+  image: 
+    src: /cancancan.png
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /README
+    - theme: alt
+      text: Installation
+      link: /installation
+
+
+features:
+  - title: "🔐 Secure Your Rails: CanCanCan's Authorization Mastery"
+    details: "Empowering developers to define and manage user permissions seamlessly."
+  - title: "🚀 Simplify with CanCanCan: Streamlined Permissions for Ruby"
+    details: "Dive into efficient, easy-to-manage access control for your Ruby applications."
+  - title: "✨ Permission Perfection with CanCanCan"
+    details: "Revolutionizing Ruby on Rails authorization with a unified, easy-to-use system."
+---
+
+## Our Sponsor
+
+<div class="sponsors">
+  <a href="https://www.pennylane.com/" target="_blank">
+    <img src="/pennylane.svg" alt="Pennylane"/>
+  </a>
+  <a href="https://www.honeybadger.io/" target="_blank">
+    <img src="/honeybadger.svg" alt="Honeybadger"/>
+  </a>
+  <a href="https://jobs.goboony.com/o/full-stack-ruby-on-rails-engineer" target="_blank">
+    <img src="/goboony.png" alt="Goboony"/>
+  </a>
+  <a href="https://www.renuo.ch" target="_blank">
+    <img src="/renuo.png" alt="Renuo AG"/>
+  </a>
+</div>
+
+<style scoped>
+.sponsors {
+  display: flex;
+  justify-content: space-around;
+  align-items: center;
+  flex-wrap: wrap;
+  margin: 2em 0;
+  gap: 10px;
+}
+
+img {
+  height: 100px;
+  width: 200px;
+  padding: 20px;
+  background: white;
+  border-radius: 10px;
+  object-fit: contain;
+  display: block;
+  margin: auto;
+}
+</style>

docs/model_adapter.md

@@ -195,15 +195,15 @@ Thus you'd probably be best served with inspecting the actual implementation of
 
 #### Implementation
 
-- [ActiveRecord Base](../lib/cancan/model_adapters/active_record_adapter.rb)
-- [ActiveRecord 4](../lib/cancan/model_adapters/active_record_4_adapter.rb)
-- [ActiveRecord 5](../lib/cancan/model_adapters/active_record_5_adapter.rb)
+- [ActiveRecord Base](https://github.com/CanCanCommunity/cancancan/blob/develop/lib/cancan/model_adapters/active_record_adapter.rb)
+- [ActiveRecord 4](https://github.com/CanCanCommunity/cancancan/blob/develop/lib/cancan/model_adapters/active_record_4_adapter.rb)
+- [ActiveRecord 5](https://github.com/CanCanCommunity/cancancan/blob/develop/lib/cancan/model_adapters/active_record_5_adapter.rb)
 
 #### Tests / Specs
 
-- [ActiveRecord Base](../spec/cancan/model_adapters/active_record_adapter_spec.rb)
-- [ActiveRecord 4](../spec/cancan/model_adapters/active_record_4_adapter_spec.rb)
-- [ActiveRecord 5](../spec/cancan/model_adapters/active_record_5_adapter_spec.rb)
+- [ActiveRecord Base](https://github.com/CanCanCommunity/cancancan/blob/develop/spec/cancan/model_adapters/active_record_adapter_spec.rb)
+- [ActiveRecord 4](https://github.com/CanCanCommunity/cancancan/blob/develop/spec/cancan/model_adapters/active_record_4_adapter_spec.rb)
+- [ActiveRecord 5](https://github.com/CanCanCommunity/cancancan/blob/develop/spec/cancan/model_adapters/active_record_5_adapter_spec.rb)
 
 **Mongoid, the adapter used in this entry as an example, can be found at:**
 

docs/public/browserconfig.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/mstile-150x150.png"/>
+            <TileColor>#ffffff</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>