Skip to content

Commit 933e634

Browse files
pandermattcoorasse
pandermatt
and
coorasse
authored
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 <coorasse@gmail.com>
1 parent 2f4c3cf commit 933e634

23 files changed

+2002
-10
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,6 @@ Gemfile.lock
1313
.ruby-version
1414
.ruby-gemset
1515
/tmp
16+
docs/.vitepress/cache
17+
node_modules
18+
docs/.vitepress/dist

‎CONTRIBUTING.md

+16
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,19 @@ Please make sure you have test coverage for anything you add or fix!
2525
Please add a CHANGELOG entry with any relevant tags for issues, pull-requests, and authors.
2626

2727
Thanks for you contribution!
28+
29+
### Modify the Documentation
30+
31+
The documentation is written in Markdown and is located in the `docs` directory. The documentation is built using [VitePress](https://vitepress.dev).
32+
VitePress supports all markdown features but also adds a few enhancements, which are documented in the [Markdown Extensions](https://vitepress.dev/guide/markdown).
33+
34+
```bash
35+
npm install
36+
npm run dev
37+
38+
# build for production, resulting in a static site in docs/.vitepress/dist
39+
npm run build
40+
```
41+
42+
Before submitting a pull request, please make sure the documentation builds correctly using `npm run build`.
43+
Most likely the build will fail if there are any syntax errors in the markdown files or dead links.

‎docs/.vitepress/config.mts

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
// https://vitepress.dev/reference/site-config
4+
export default defineConfig({
5+
title: "CanCanCan",
6+
description: "The authorization Gem for Ruby on Rails.",
7+
head: [
8+
['link', { rel: "apple-touch-icon", sizes: "180x180", href: "/apple-touch-icon.png" }],
9+
['link', { rel: "icon", type: "image/png", sizes: "32x32", href: "/favicon-32x32.png" }],
10+
['link', { rel: "icon", type: "image/png", sizes: "16x16", href: "/favicon-16x16.png" }],
11+
['link', { rel: "mask-icon", href: "./safari-pinned-tab.svg", color: "#3c3ebf" }],
12+
13+
['link', { rel: "icon", href: "/favicon.ico", type: "image/x-icon" }],
14+
['link', { rel: "shortcut icon", href: "/favicon.ico", type: "image/x-icon" }],
15+
],
16+
sitemap: {
17+
hostname: 'https://cancancan.dev'
18+
},
19+
cleanUrls: true,
20+
themeConfig: {
21+
// https://vitepress.dev/reference/default-theme-config
22+
nav: [
23+
{ text: 'Docs', link: '/README' },
24+
{ text: 'Changelog', link: 'https://github.com/CanCanCommunity/cancancan/blob/main/CHANGELOG.md' },
25+
{
26+
text: 'Screencasts',
27+
items: [
28+
{ text: 'Screencast 1', link: 'http://railscasts.com/episodes/192-authorization-with-cancan' },
29+
{ text: 'Screencast 2', link: 'https://www.youtube.com/watch?v=cTYu-OjUgDw' }
30+
]
31+
},
32+
],
33+
34+
footer: {
35+
message: 'Made with ❤️ by the <a href="https://github.com/CanCanCommunity/cancancan/graphs/contributors" target="_blank">CanCanCan community</a>',
36+
copyright: `${new Date().getFullYear()} CanCanCan`
37+
},
38+
externalLinkIcon: true,
39+
40+
lastUpdated: {
41+
formatOptions: {
42+
dateStyle: 'medium',
43+
}
44+
},
45+
editLink: {
46+
pattern: 'https://github.com/CanCanCommunity/cancancan/edit/main/docs/:path'
47+
},
48+
search: {
49+
provider: 'local'
50+
},
51+
52+
logo: '/cancancan.png',
53+
54+
sidebar: [
55+
{
56+
text: 'Guide',
57+
items: [
58+
{ text: 'Introduction', link: '/introduction' },
59+
{ text: 'Installation', link: '/installation' },
60+
{ text: 'Define and check abilities', link: '/define_check_abilities' },
61+
{ text: 'Controller helpers', link: '/controller_helpers' },
62+
{ text: 'Fetching records', link: '/fetching_records' },
63+
{ text: 'Cannot', link: '/cannot' },
64+
{ text: 'Hash of conditions', link: '/hash_of_conditions' },
65+
{ text: 'Combine Abilities', link: '/combine_abilities' },
66+
{ text: 'Check abilities - avoid mistakes', link: '/check_abilities_mistakes' },
67+
{ text: 'Handling CanCan::AccessDenied', link: '/handling_access_denied' },
68+
{ text: 'Customize controller helpers', link: '/changing_defaults' },
69+
{ text: 'Accessing request data', link: '/accessing_request_data' },
70+
{ text: 'SQL strategies', link: '/sql_strategies' },
71+
{ text: 'Accessible attributes', link: '/accessible_attributes' },
72+
{ text: 'Testing', link: '/testing' },
73+
{ text: 'Internationalization', link: '/internationalization' }
74+
]
75+
},
76+
{
77+
text: 'Further topics',
78+
items: [
79+
{ text: 'Migrating', link: '/migrating' },
80+
{ text: 'Debugging Abilities', link: '/debugging' },
81+
{ text: 'Split your ability file', link: '/split_ability' },
82+
{ text: 'Define Abilities - best practices', link: '/define_abilities_best_practices' },
83+
{ text: 'Abilities in database', link: '/abilities_in_database' },
84+
{ text: 'Role-based Authorization', link: '/role_based_authorization' },
85+
{ text: 'Model Adapter', link: '/model_adapter' },
86+
{ text: 'Rules compression', link: '/rules_compression' },
87+
{ text: 'Inherited Resources', link: '/inherited_resources' },
88+
{ text: 'Devise', link: '/devise' },
89+
{ text: 'FriendlyId', link: '/friendly_id' }
90+
]
91+
}
92+
],
93+
socialLinks: [
94+
{ icon: 'github', link: 'https://github.com/CanCanCommunity/cancancan' }
95+
]
96+
}
97+
})

‎docs/.vitepress/theme/index.ts

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// https://vitepress.dev/guide/custom-theme
2+
import { h } from 'vue'
3+
import type { Theme } from 'vitepress'
4+
import DefaultTheme from 'vitepress/theme'
5+
import './style.css'
6+
7+
export default {
8+
extends: DefaultTheme,
9+
Layout: () => {
10+
return h(DefaultTheme.Layout, null, {
11+
// https://vitepress.dev/guide/extending-default-theme#layout-slots
12+
})
13+
},
14+
enhanceApp({ app, router, siteData }) {
15+
}
16+
} satisfies Theme

‎docs/.vitepress/theme/style.css

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
/**
2+
* Customize default theme styling by overriding CSS variables:
3+
* https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
4+
*/
5+
6+
/**
7+
* Colors
8+
*
9+
* Each colors have exact same color scale system with 3 levels of solid
10+
* colors with different brightness, and 1 soft color.
11+
*
12+
* - `XXX-1`: The most solid color used mainly for colored text. It must
13+
* satisfy the contrast ratio against when used on top of `XXX-soft`.
14+
*
15+
* - `XXX-2`: The color used mainly for hover state of the button.
16+
*
17+
* - `XXX-3`: The color for solid background, such as bg color of the button.
18+
* It must satisfy the contrast ratio with pure white (#ffffff) text on
19+
* top of it.
20+
*
21+
* - `XXX-soft`: The color used for subtle background such as custom container
22+
* or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
23+
* on top of it.
24+
*
25+
* The soft color must be semi transparent alpha channel. This is crucial
26+
* because it allows adding multiple "soft" colors on top of each other
27+
* to create a accent, such as when having inline code block inside
28+
* custom containers.
29+
*
30+
* - `default`: The color used purely for subtle indication without any
31+
* special meanings attched to it such as bg color for menu hover state.
32+
*
33+
* - `brand`: Used for primary brand colors, such as link text, button with
34+
* brand theme, etc.
35+
*
36+
* - `tip`: Used to indicate useful information. The default theme uses the
37+
* brand color for this by default.
38+
*
39+
* - `warning`: Used to indicate warning to the users. Used in custom
40+
* container, badges, etc.
41+
*
42+
* - `danger`: Used to show error, or dangerous message to the users. Used
43+
* in custom container, badges, etc.
44+
* -------------------------------------------------------------------------- */
45+
46+
:root {
47+
--vp-c-default-1: var(--vp-c-gray-1);
48+
--vp-c-default-2: var(--vp-c-gray-2);
49+
--vp-c-default-3: var(--vp-c-gray-3);
50+
--vp-c-default-soft: var(--vp-c-gray-soft);
51+
52+
--vp-c-brand-1: var(--vp-c-indigo-1);
53+
--vp-c-brand-2: var(--vp-c-indigo-2);
54+
--vp-c-brand-3: var(--vp-c-indigo-3);
55+
--vp-c-brand-soft: var(--vp-c-indigo-soft);
56+
57+
--vp-c-tip-1: var(--vp-c-brand-1);
58+
--vp-c-tip-2: var(--vp-c-brand-2);
59+
--vp-c-tip-3: var(--vp-c-brand-3);
60+
--vp-c-tip-soft: var(--vp-c-brand-soft);
61+
62+
--vp-c-warning-1: var(--vp-c-yellow-1);
63+
--vp-c-warning-2: var(--vp-c-yellow-2);
64+
--vp-c-warning-3: var(--vp-c-yellow-3);
65+
--vp-c-warning-soft: var(--vp-c-yellow-soft);
66+
67+
--vp-c-danger-1: var(--vp-c-red-1);
68+
--vp-c-danger-2: var(--vp-c-red-2);
69+
--vp-c-danger-3: var(--vp-c-red-3);
70+
--vp-c-danger-soft: var(--vp-c-red-soft);
71+
}
72+
73+
.dark .VPImage.logo {
74+
filter: brightness(0) invert(1);
75+
}
76+
77+
/**
78+
* Component: Button
79+
* -------------------------------------------------------------------------- */
80+
81+
:root {
82+
--vp-button-brand-border: transparent;
83+
--vp-button-brand-text: var(--vp-c-white);
84+
--vp-button-brand-bg: var(--vp-c-brand-3);
85+
--vp-button-brand-hover-border: transparent;
86+
--vp-button-brand-hover-text: var(--vp-c-white);
87+
--vp-button-brand-hover-bg: var(--vp-c-brand-2);
88+
--vp-button-brand-active-border: transparent;
89+
--vp-button-brand-active-text: var(--vp-c-white);
90+
--vp-button-brand-active-bg: var(--vp-c-brand-1);
91+
}
92+
93+
/**
94+
* Component: Home
95+
* -------------------------------------------------------------------------- */
96+
97+
:root {
98+
--vp-home-hero-name-color: transparent;
99+
--vp-home-hero-name-background: -webkit-linear-gradient(
100+
120deg,
101+
#bd34fe 30%,
102+
#41d1ff
103+
);
104+
}
105+
106+
@media (min-width: 640px) {
107+
:root {
108+
--vp-home-hero-image-filter: blur(56px);
109+
}
110+
}
111+
112+
@media (min-width: 960px) {
113+
:root {
114+
--vp-home-hero-image-filter: blur(68px);
115+
}
116+
}
117+
118+
/**
119+
* Component: Custom Block
120+
* -------------------------------------------------------------------------- */
121+
122+
:root {
123+
--vp-custom-block-tip-border: transparent;
124+
--vp-custom-block-tip-text: var(--vp-c-text-1);
125+
--vp-custom-block-tip-bg: var(--vp-c-brand-soft);
126+
--vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
127+
}
128+
129+
/**
130+
* Component: Algolia
131+
* -------------------------------------------------------------------------- */
132+
133+
.DocSearch {
134+
--docsearch-primary-color: var(--vp-c-brand-1) !important;
135+
}
136+

‎docs/check_abilities_mistakes.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ cannot? :destroy, @article
1414

1515
What we want to explain you in this chapter is that you can also pass the class instead of a single instance:
1616

17-
```rhtml
17+
```erb
1818
<% if can? :create, Project %>
1919
<%= link_to "New Project", new_project_path %>
2020
<% end %>

‎docs/index.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
# https://vitepress.dev/reference/default-theme-home-page
3+
layout: home
4+
5+
hero:
6+
name: CanCanCan
7+
text: Developer guide
8+
tagline: The authorization Gem for Ruby on Rails.
9+
image:
10+
src: /cancancan.png
11+
style:
12+
# for dark mode
13+
backgroundColor: '#fff'
14+
borderRadius: '50%'
15+
padding: '20px'
16+
actions:
17+
- theme: brand
18+
text: Get Started
19+
link: /README
20+
- theme: alt
21+
text: Installation
22+
link: /installation
23+
- theme: alt
24+
text: GitHub
25+
link: https://github.com/CanCanCommunity/cancancan
26+
27+
features:
28+
- title: "🔐 Secure Your Rails: CanCanCan's Authorization Mastery"
29+
details: "Empowering developers to define and manage user permissions seamlessly."
30+
- title: "🚀 Simplify with CanCanCan: Streamlined Permissions for Ruby"
31+
details: "Dive into efficient, easy-to-manage access control for your Ruby applications."
32+
- title: "✨ Permission Perfection with CanCanCan"
33+
details: "Revolutionizing Ruby on Rails authorization with a unified, easy-to-use system."
34+
---
35+
36+
## Our Sponsor
37+
38+
<VPSponsors :data="sponsors" />
39+
40+
<script setup>
41+
import { VPSponsors } from 'vitepress/theme'
42+
43+
let sponsors = [
44+
{
45+
name: 'Pennylane',
46+
img: '/pennylane.svg',
47+
url: 'https://www.pennylane.com/'
48+
},
49+
{
50+
name: 'Honeybadger',
51+
img: '/honeybadger.svg',
52+
url: 'https://www.honeybadger.io/'
53+
},
54+
{
55+
name: 'Goboony',
56+
img: '/goboony.png',
57+
url: 'https://jobs.goboony.com'
58+
},
59+
{
60+
name: 'Renuo AG',
61+
img: '/renuo.png',
62+
url: 'https://www.renuo.ch'
63+
}
64+
]
65+
</script>
66+
67+
_Do you want to sponsor CanCanCan and show your logo here? Check our [Sponsors Page](https://github.com/sponsors/coorasse)._
68+
69+
## Questions?
70+
71+
If you have any question or doubt regarding CanCanCan which you cannot find the solution to in the
72+
[documentation](./README.md), please
73+
[open a question on Stackoverflow](http://stackoverflow.com/questions/ask?tags=cancancan) with tag
74+
[cancancan](http://stackoverflow.com/questions/tagged/cancancan)
75+
76+
## Bugs?
77+
78+
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.
79+
80+
## Special Thanks
81+
82+
Thanks to our Sponsors and to all the [CanCanCan contributors](https://github.com/CanCanCommunity/cancancan/contributors).
83+
See the [CHANGELOG](https://github.com/CanCanCommunity/cancancan/blob/main/CHANGELOG.md) for the full list.

‎docs/introduction.md

+18-1
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,23 @@ If you'd like to sponsor this library, head to <https://github.com/sponsors/coor
2626

2727
Thank you,
2828

29-
Alessandro Rodi
29+
<VPTeamMembers size="small" :members="members" />
3030

3131
Head to the [Installation](./installation.md) chapter.
32+
33+
<script setup>
34+
import { VPTeamMembers } from 'vitepress/theme'
35+
36+
const members = [
37+
{
38+
avatar: 'https://avatars.githubusercontent.com/u/1319150',
39+
name: 'Alessandro Rodi',
40+
title: 'Maintainer',
41+
sponsor: 'https://github.com/sponsors/coorasse',
42+
links: [
43+
{ icon: 'github', link: 'https://github.com/coorasse' },
44+
{ icon: 'twitter', link: 'https://twitter.com/coorasse' }
45+
]
46+
},
47+
]
48+
</script>

0 commit comments

Comments
 (0)