add docs page to cancancan using vitepress (#841)

* add docs page to cancancan using vitepress * add icons * Change GitHub link * Add GitHub to index.md * add footer and more nav items * add team widget * fix link * add contributing * update md * add sonsor * use vitepress sponsor component * Update config.mts * update vitepress to the public release * update vitepress * Update docs/.vitepress/config.mts --------- Co-authored-by: Alessandro Rodi <[email protected]>
CanCanCommunity · May 23, 2024 · 933e634 · 933e634
1 parent 2f4c3cf
commit 933e634
Show file tree

Hide file tree

Showing 23 changed files with 2,002 additions and 10 deletions.
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,6 @@ Gemfile.lock
 .ruby-version
 .ruby-gemset
 /tmp
+docs/.vitepress/cache
+node_modules
+docs/.vitepress/dist
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -25,3 +25,19 @@ Please make sure you have test coverage for anything you add or fix!
 Please add a CHANGELOG entry with any relevant tags for issues, pull-requests, and authors.
 
 Thanks for you contribution!
+
+### Modify the Documentation
+
+The documentation is written in Markdown and is located in the `docs` directory. The documentation is built using [VitePress](https://vitepress.dev).
+VitePress supports all markdown features but also adds a few enhancements, which are documented in the [Markdown Extensions](https://vitepress.dev/guide/markdown).
+
+```bash
+npm install
+npm run dev
+
+# build for production, resulting in a static site in docs/.vitepress/dist
+npm run build
+```
+
+Before submitting a pull request, please make sure the documentation builds correctly using `npm run build`.
+Most likely the build will fail if there are any syntax errors in the markdown files or dead links.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -0,0 +1,97 @@
+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: "icon", href: "/favicon.ico", type: "image/x-icon" }],
+    ['link', { rel: "shortcut icon", href: "/favicon.ico", type: "image/x-icon" }],
+  ],
+  sitemap: {
+    hostname: 'https://cancancan.dev'
+  },
+  cleanUrls: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Docs', link: '/README' },
+      { text: 'Changelog', link: 'https://github.com/CanCanCommunity/cancancan/blob/main/CHANGELOG.md' },
+      {
+        text: 'Screencasts',
+        items: [
+          { text: 'Screencast 1', link: 'http://railscasts.com/episodes/192-authorization-with-cancan' },
+          { text: 'Screencast 2', link: 'https://www.youtube.com/watch?v=cTYu-OjUgDw' }
+        ]
+      },
+    ],
+
+    footer: {
+      message: 'Made with ❤️ by the <a href="https://github.com/CanCanCommunity/cancancan/graphs/contributors" target="_blank">CanCanCan community</a>',
+      copyright: `${new Date().getFullYear()} CanCanCan`
+    },
+    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: 'Guide',
+        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/CanCanCommunity/cancancan' }
+    ]
+  }
+})
diff --git a/docs/.vitepress/theme/index.ts b/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
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
@@ -0,0 +1,136 @@
+/**
+ * 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);
+}
+
+.dark .VPImage.logo {
+  filter: brightness(0) invert(1);
+}
+
+/**
+ * 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
+  );
+}
+
+@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;
+}
+
diff --git a/docs/check_abilities_mistakes.md b/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 %>

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,83 @@
+---
+# 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
+    style:
+      # for dark mode
+      backgroundColor: '#fff'
+      borderRadius: '50%'
+      padding: '20px'
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /README
+    - theme: alt
+      text: Installation
+      link: /installation
+    - theme: alt
+      text: GitHub
+      link: https://github.com/CanCanCommunity/cancancan
+
+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
+
+<VPSponsors :data="sponsors" />
+
+<script setup>
+import { VPSponsors } from 'vitepress/theme'
+
+let sponsors = [
+  {
+    name: 'Pennylane',
+    img: '/pennylane.svg',
+    url: 'https://www.pennylane.com/'
+  },
+  {
+    name: 'Honeybadger',
+    img: '/honeybadger.svg',
+    url: 'https://www.honeybadger.io/'
+  },
+  {
+    name: 'Goboony',
+    img: '/goboony.png',
+    url: 'https://jobs.goboony.com'
+  },
+  {
+    name: 'Renuo AG',
+    img: '/renuo.png',
+    url: 'https://www.renuo.ch'
+  }
+]
+</script>
+
+_Do you want to sponsor CanCanCan and show your logo here? Check our [Sponsors Page](https://github.com/sponsors/coorasse)._
+
+## Questions?
+
+If you have any question or doubt regarding CanCanCan which you cannot find the solution to in the
+[documentation](./README.md), please
+[open a question on Stackoverflow](http://stackoverflow.com/questions/ask?tags=cancancan) with tag
+[cancancan](http://stackoverflow.com/questions/tagged/cancancan)
+
+## Bugs?
+
+If you find a bug please add an [issue on GitHub](https://github.com/CanCanCommunity/cancancan/issues) or fork the project and send a pull request.
+
+## Special Thanks
+
+Thanks to our Sponsors and to all the [CanCanCan contributors](https://github.com/CanCanCommunity/cancancan/contributors).
+See the [CHANGELOG](https://github.com/CanCanCommunity/cancancan/blob/main/CHANGELOG.md) for the full list.
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -26,6 +26,23 @@ If you'd like to sponsor this library, head to <https://github.com/sponsors/coor
 
 Thank you,
 
-Alessandro Rodi
+<VPTeamMembers size="small" :members="members" />
 
 Head to the [Installation](./installation.md) chapter.
+
+<script setup>
+import { VPTeamMembers } from 'vitepress/theme'
+
+const members = [
+  {
+    avatar: 'https://avatars.githubusercontent.com/u/1319150',
+    name: 'Alessandro Rodi',
+    title: 'Maintainer',
+    sponsor: 'https://github.com/sponsors/coorasse',
+    links: [
+      { icon: 'github', link: 'https://github.com/coorasse' },
+      { icon: 'twitter', link: 'https://twitter.com/coorasse' }
+    ]
+  },
+]
+</script>