Twill 3.0 docs updates

Author: ifox

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 <!--
   Thanks for opening a PR! Your contribution is much appreciated.
-  Do you have any questions? Check out the contributing docs at https://github.com/area17/twill/blob/2.x/CONTRIBUTING.md, 
+  Do you have any questions? Check out the contributing docs at https://github.com/area17/twill/blob/3.x/CONTRIBUTING.md, 
   or ask in this Pull Request and a Twill maintainer will be happy to help :)
 -->
 

README.md

@@ -41,7 +41,7 @@ Over the last 15 years, nearly every engineer at AREA 17 has contributed to Twil
 With contributions from Laurens van Heems, Fernando Petrelli, Gilbert Moufflet, Mubashar Iqbal, Pablo Barrios, Luis Lavena, and Mike Byrne.
 
 # Contributing
-We look forward to your contribution to make Twill the best it can be. You can find our contribution guidelines in the Twill [documentation](https://twill.io/docs#contribution-guide).
+We look forward to your contribution to make Twill the best it can be. You can find our contribution guidelines in the Twill [documentation](https://twill.io/docs/#content-contribution-guide).
 
 # Security vulnerabilities
 If you discover a security vulnerability within Twill, please email us at [[email protected]](mailto:[email protected]). All security vulnerabilities will be promptly addressed.

SECURITY.md

@@ -3,9 +3,9 @@
 ## Supported Versions
 
 | Version | Supported          |
-| ------- | ------------------ |
-| 3.x   | :white_check_mark: |
-| 2.x   | :white_check_mark: |
+|---------|--------------------|
+| 3.x     | :white_check_mark: |
+| 2.x     | :white_check_mark: |
 | 1.2.x   | :white_check_mark: |
 | < 1.2   | :x:                |
 

config/media_library.php

@@ -16,6 +16,7 @@
     | If using the 'local' endpoint type, define a 'local_path' to store files.
     | Supported image services:
     | - 'A17\Twill\Services\MediaLibrary\Imgix'
+    | - 'A17\Twill\Services\MediaLibrary\TwicPics'
     | - 'A17\Twill\Services\MediaLibrary\Local'
     |
      */

docs/_templates/assets/twill_cms_three_logo.png

@@ -48,7 +48,7 @@
         <a
             class="text-link !no-underline"
             href="{{$githubLink}}"
-            ref="noopener noreferrer"
+            rel="noopener noreferrer"
             target="_blank">
             Edit this page on Github
         </a>

docs/_templates/components/contentFooter.blade.php

@@ -6,7 +6,7 @@
             <a class="card__link" href="{{ $item['url'] }}">{{ $item['title'] }}</a>
             @isset($item["metadata"]["summary"])<span class="card__summary">{{ $item["metadata"]["summary"] }}</span>@endisset
             @isset($item["metadata"]["tag"])<em class="card__tag">{{ $item["metadata"]["tag"] }}</em>@endisset
-            @isset($item["metadata"]["date"])<stemrong class="card__date">{{ $item["metadata"]["date"] }}</em>@endisset
+            @isset($item["metadata"]["date"])<em class="card__date">{{ $item["metadata"]["date"] }}</em>@endisset
         </p>
     </div>
     @endforeach

docs/_templates/components/grid-auto-generated.blade.php

@@ -7,8 +7,9 @@
             <x-twilldocs::navLink url="https://twill.io/made" label="#MadeWithTwill" branded />
             <x-twilldocs::navLink url="https://demo.twill.io/" label="Demo" />
             <x-twilldocs::navLink url="https://discord.gg/cnWk7EFv8R" label="Chat" />
-            <x-twilldocs::navLink url="https://twill.io/blog" label="Blog" />
-            <x-twilldocs::navLink url="https://twill.io/docs" label="Docs" />
+            <x-twilldocs::navLink url="/blog/" label="Blog" />
+            <x-twilldocs::navLink url="/guides/" label="Guides" />
+            <x-twilldocs::navLink url="/docs/" label="Docs" />
             <div id="docsearch"></div>
             <x-twilldocs::githubBtn />
             <x-twilldocs::menuBtn />

docs/_templates/components/header.blade.php

@@ -37,8 +37,8 @@
     margin-top: 0;
   }
 
-  .chapters-nav-fixed > ul {
-    @apply p-20 border border-primary;
+  .chapters-nav-fixed > div > ul {
+    @apply pt-20;
   }
 
   .chapters-nav-fixed > div > ul > li {

docs/_templates/css/chaptersNav.css

@@ -8,7 +8,7 @@
     @apply f-h1 mt-68;
   }
 
-  body[class*="page--blogs"]:not([class~="page--blogs-index"]) .markdown h1 {
+  body[class*="page--blog"]:not([class~="page--blog-index"]) .markdown h1 {
     @apply f-headline;
   }
 
@@ -25,6 +25,10 @@
     @apply f-h4 mt-20 font-bold;
   }
 
+  .markdown h5 {
+    @apply f-h4 mt-20 font-bold;
+  }
+
   .markdown p {
     @apply f-body;
   }

docs/_templates/css/markdown.css

@@ -1,7 +1,6 @@
 // active scroll nav behavior
 const ACTIVE_CLASS = 'text-link'
 const LIST_ACTIVE = 'is-active'
-const INACTIVE_CLASS = 'text-black'
 const nav = document.querySelector('.chapters-nav-fixed')
 const headerHeight = 80
 
@@ -15,7 +14,7 @@ if (nav) {
 
   // helper function to get the correct titles href
   const _getActiveHref = (titles, pos) => {
-    let current = []
+    const current = []
     titles.forEach(el => {
       // get height to top of page from title
       const offset = el.getBoundingClientRect()
@@ -33,15 +32,14 @@ if (nav) {
 
     // pluck the last (most recent) item from that array and serve that :)
     // OR if undefined, return the first item
-    let currentActiveIndex = current[current.length - 1]
+    return current[current.length - 1]
       ? current[current.length - 1]
-      : chapterItems .length > 0 ? (chapterItems[0].querySelector('a') ? `#${chapterItems[0].querySelector('a').getAttribute('id')}` : -1) : -1
-    return currentActiveIndex
+      : chapterItems.length > 0 ? (chapterItems[0].querySelector('a') ? `#${chapterItems[0].querySelector('a').getAttribute('id')}` : -1) : -1
   }
 
   const setActiveNav = pos => {
     const active = _getActiveHref(chapterItems, pos)
-    console.log(active);
+
     navItems.forEach(elem => {
       const linkEl = elem.querySelector('a')
       const listEl = elem

docs/_templates/js/nav.js

@@ -9,7 +9,40 @@
   <meta charset="UTF-8">
   <meta http-equiv="X-UA-Compatible" content="ie=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>{{ $title }}</title>
+  <title>{{ $seoTitle ?? ($title . ' — Twill CMS') }}</title>
+  <link rel="mask-icon" href="/dist/images/favicons/safari-pinned-tab.svg?v=3" color="#000000">
+  <meta name="msapplication-TileColor" content="#ffffff">
+  <meta name="theme-color" content="#000000">
+  <meta property="og:image" content="https://twill.io/dist/images/social_share.png" />
+  <meta property="og:image:width" content="1200" />
+  <meta property="og:image:height" content="630" />
+
+  <meta name="twitter:image" content="https://twill.io/dist/images/social_share.png">
+  <meta itemprop="image" content="https://twill.io/dist/images/social_share.png">
+
+  <!-- Facebook / Open Graph globals -->
+  <meta property="og:type" content="website" />
+  <meta property="og:site_name" content="Twill" />
+  <meta property="og:author" content="https://www.facebook.com/twillcms/" />
+
+  <!-- Twitter globals -->
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:site" content="@twillcms" />
+  <meta name="twitter:domain" content="twill.io" />
+  <meta name="twitter:creator" content="@twillcms" />
+
+  <!-- Main Favicon -->
+  <link rel="shortcut icon" href="/dist/images/favicons/favicon.ico">
+  <!-- Apple Touch Icons (ipad/iphone standard+retina) -->
+  <link rel="apple-touch-icon" href="/dist/images/favicons/favicon-192.png">
+  <!-- General use iOS/Android icon, auto-downscaled by devices. -->
+  <link rel="apple-touch-icon" type="image/png" href="/dist/images/favicons/favicon-192.png" sizes="192x192">
+  <!-- iPhone retina touch icon -->
+  <link rel="apple-touch-icon" type="image/png" href="/dist/images/favicons/favicon-180.png" sizes="180x180">
+  <!-- iPad home screen icons -->
+  <!-- Favicon Fallbacks for old browsers that don't read .ico -->
+  <link rel="icon" type="image/png" href="/dist/images/favicons/favicon-32.png" sizes="32x32">
+  <link rel="icon" type="image/png" href="/dist/images/favicons/favicon-16.png" sizes="16x16">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link rel="preconnect" href="https://89hnjpxalf-dsn.algolia.net" crossorigin />
@@ -20,6 +53,16 @@
   <script src="//unpkg.com/alpinejs" defer></script>
 </head>
 
+<!-- Google tag (gtag.js) -->
+{{--<script async src="https://www.googletagmanager.com/gtag/js?id=G-EE0Y26M81B"></script>--}}
+{{--<script>--}}
+{{--    window.dataLayer = window.dataLayer || [];--}}
+{{--    function gtag(){dataLayer.push(arguments);}--}}
+{{--    gtag('js', new Date());--}}
+
+{{--    gtag('config', 'G-EE0Y26M81B');--}}
+{{--</script>--}}
+
 <body
   class="overflow-x-hidden page--{{ Str::slug(Str::replace(['/', '.html'], ['-', ''], $url)) }}"
   x-data="{ isMobile: (window.innerWidth < {{ intval($feConfig['structure']['breakpoints']['lg']) }}) ? true : false, openNav: false }"
@@ -41,14 +84,14 @@ class="overflow-x-hidden page--{{ Str::slug(Str::replace(['/', '.html'], ['-', '
         {!! $content !!}
         <x-twilldocs::grid-auto-generated :tree="$tree" :currentSegment="$currentSegment" :url="$url" />
       </div>
-    @elseif ($currentSegment === 'blogs' && strpos($url, 'index.html'))
+    @elseif ($currentSegment === 'blog' && strpos($url, 'index.html'))
       {{-- blog index --}}
       <div class="content markdown mt-68">
         <h1>{{$title}}</h1>
         {!! $content !!}
         <x-twilldocs::grid-auto-generated :tree="$tree" :currentSegment="$currentSegment" :url="$url" />
       </div>
-    @elseif ($currentSegment === 'documentation' || $currentSegment === 'guides')
+    @elseif ($currentSegment === 'docs' || $currentSegment === 'guides')
       <div class="flex flex-row flex-nowrap justify-between">
         <x-twilldocs::sidebar :tree="$tree" :currentSegment="$currentSegment" :url="$url"/>
         <div class="content markdown w-full lg:w-9-cols xl:w-6-cols lg:max-w-740 xl:mx-auto">
@@ -84,7 +127,7 @@ class="overflow-x-hidden page--{{ Str::slug(Str::replace(['/', '.html'], ['-', '
         <h1>{{$title}}</h1>
         {!! $content !!}
       </div>
-    @elseif ($currentSegment === 'blogs')
+    @elseif ($currentSegment === 'blog')
       {{-- blog details --}}
       <div class="flex flex-row flex-nowrap">
         <div class="content markdown w-full lg:w-9-cols xl:w-6-cols lg:max-w-740 lg:mx-auto mt-68">

docs/_templates/layout.blade.php

@@ -1,7 +1,7 @@
 # User Management
 
 Authentication and authorization are provided by default in Laravel. This package simply leverages what Laravel provides
-and configures the views for you. By default, users can login at `/login` and can also reset their password through that
+and configures the views for you. By default, users can log in at `/login` and can also reset their password through that
 same screen. New users have to reset their password before they can gain access to the admin application. By using the
 twill configuration file, you can change the default redirect path (`auth_login_redirect_path`) and send users to
 anywhere in your application following login.
@@ -40,7 +40,7 @@ Admin users have the same permissions as publisher users plus:
 - full permissions on users
 
 There is also a super admin user that can impersonate other users at `/users/impersonate/{id}`.
-The super admin can be a useful tool for testing features with different user roles without having to logout/login
+The super admin can be a useful tool for testing features with different user roles without having to log out/login
 manually,
 as well as for debugging issues reported by specific users. You can stop impersonating by going
 to `/users/impersonate/stop`.
@@ -82,9 +82,8 @@ class AppServiceProvider extends ServiceProvider
 }
 ```
 
-Finally, in your `AuthServiceProvider` class,
-redefine [Twill's default permissions](https://github.com/area17/twill/blob/e8866e40b7df4a6919e0ddb368990d04caeb705a/src/AuthServiceProvider.php#L26-L48)
-if you need to, or add your own, for example:
+Finally, in your `AuthServiceProvider` class, redefine [Twill's default permissions](https://github.com/area17/twill/blob/e8866e40b7df4a6919e0ddb368990d04caeb705a/src/AuthServiceProvider.php#L26-L48) if you need to, or 
+add your own, for example:
 
 ```php
 <?php
@@ -124,7 +123,7 @@ class AuthServiceProvider extends ServiceProvider
 }
 ```
 
-If you need a more dynamic aproach you can also get the current permission enum using the facade:
+If you need a more dynamic approach you can also get the current permission enum using the facade:
 
 ```php
 TwillPermissons::roles()::PUBLISHER (or any role)
@@ -141,12 +140,10 @@ You can use your new permission and existing ones in many places like the `twill
 ```
 
 Also in forms blade files using `@can`, as well as in middleware definitions in routes or controllers,
-see [Laravel's documentation](https://laravel.com/docs/10.x/authorization#via-middleware) for more info.
+see [Laravel documentation](https://laravel.com/docs/10.x/authorization#via-middleware) for more info.
 
 You should follow the Laravel documentation regarding [authorization](https://laravel.com/docs/10.x/authorization). It's
-pretty good. Also if you would like to bring administration of roles and permissions to the admin
-application, [spatie/laravel-permission](https://github.com/spatie/laravel-permission) would probably be your best
-friend.
+pretty good.
 
 ## Auto login
 

docs/content/1_documentation/13_user-management/1_index.md docs/content/1_docs/10_user-management/1_index.md

@@ -19,11 +19,11 @@ return [
 ];
 ```
 
-In addition to this we have to configure the permissions system. There are 3 levels to choose from:
+In addition to this we have to configure the permissions' system. There are 3 levels to choose from:
 
-- [**role**](#level-role): this manages the access of modules based on the role of a user
-- [**roleGroup**](#level-rolegroup): this manages the access of modules for a group of users, in addition to `role`
-- [**roleGroupItem**](#level-rolegroupitem): this manages the permission of items within a module, in addition
+- [**role**](#content-level-role): this manages the access of modules based on the role of a user
+- [**roleGroup**](#content-level-rolegroup): this manages the access of modules for a group of users, in addition to `role`
+- [**roleGroupItem**](#content-level-rolegroupitem): this manages the permission of items within a module, in addition
   to `roleGroup`
 
 Set the `twill.permissions.level` to the desired type. And also set the modules to manage in
@@ -43,7 +43,7 @@ return [
 ]
 ```
 
-Once you have setup permission-management, make sure to run your database migrations:
+Once you have set up permission-management, make sure to run your database migrations:
 
 ```
 php artisan migrate
@@ -62,16 +62,12 @@ The permission migration seeds 4 roles by default:
 - **Team**: Empty role, without permissions by default.
 - **Guest**: Empty role, without permissions by default. But not added to the "Everyone" group.
 
-Below is a screenshot of the admin role to illustrate the options you can configure per role:
-
-![Admin role](./assets/admin-role-screen.png)
-
 ## Level: RoleGroup
 
 At it's core the RoleGroup level is the same as the Role level, however we now have an additional layer that can be used
 to further Group the users.
 
-By default there is only one group "Everyone" where every user belongs to except for "Guests".
+By default, there is only one group "Everyone" where every user belongs to except for "Guests".
 
 You can use Roles in combination with Groups to have more control over the permission a user gets.
 
@@ -81,11 +77,6 @@ module.
 Now you can have a group "Module 1" and "Module 2", together with the "administrator" role, each user can only access
 the content for their groups.
 
-![Group screen](./assets/group-screen.png)
-
 ## Level: RoleGroupItem
 
-With RoleGroupItem you get all of the above. The difference is that you can also set permissions on a per entity level.
-
-![User access control](./assets/user-access-control.png)
-
+With RoleGroupItem you get all of the above. The difference is that you can also set permissions on a per-entity level.

docs/content/1_documentation/13_user-management/2_advanced-permissions.md docs/content/1_docs/10_user-management/2_advanced-permissions.md

@@ -1,12 +1,10 @@
 # Dashboard
 
-Once you have created and configured multiple CRUD modules in your Twill's admin console, you can configure Twill's
-dashboard in `config/twill.php`.
+Once you have created and configured multiple CRUD modules in your Twill's admin console, you can configure Twill's  dashboard in `config/twill.php`.
 
 ## Model activity
 
-For each module that you want to enable in a part or all parts of the dashboad, add an entry to the `dashboard.modules`
-array, like in the following example:
+For each module that you want to enable in a part or all parts of the dashboard, add an entry to the `dashboard.modules` array, like in the following example:
 
 ```php
 return [
@@ -31,7 +29,7 @@ return [
 ];
 ```
 
-## Google analytics
+## Google Analytics
 
 You can also enable a Google Analytics module:
 
@@ -50,9 +48,7 @@ return [
 
 It is using Spatie's [Laravel Analytics](https://github.com/spatie/laravel-analytics) package.
 
-Follow [Spatie's documentation](https://github.com/spatie/laravel-analytics#how-to-obtain-the-credentials-to-communicate-with-google-analytics)
-to setup a Google service account and download a json file containing your credentials, and provide your Analytics view
-ID using the `ANALYTICS_VIEW_ID` environment variable.
+Follow [Spatie's documentation](https://github.com/spatie/laravel-analytics#how-to-obtain-the-credentials-to-communicate-with-google-analytics) to set up a Google service account and download a json file containing your credentials, and provide your Analytics view ID using the `ANALYTICS_VIEW_ID` environment variable.
 
 ## User activity
 

docs/content/1_documentation/14_oauth-login/1_index.md docs/content/1_docs/10_user-management/3_oauth-login

@@ -48,8 +48,7 @@ php artisan twill:make:capsule Project --packageDirectory=./packages/twill-exten
 
 The command above will create a capsule, if you want to create a singleton capsule you could use `php artisan twill:make:capsule --singleton` instead.
 
-Once this is done you already can go ahead and refresh your twill admin and the new
-capsule should appear in the menu!
+Once this is done you already can go ahead and refresh your twill admin and the new capsule should appear in the menu!
 
 If you get an error when visiting, do not forget to run your database migrations.
 

docs/content/1_documentation/13_user-management/assets/admin-role-screen.png docs/content/1_docs/10_user-management/assets/admin-role-screen.png

@@ -1,12 +1,12 @@
 # Packages
 
-Packages are a great way to add or create reusable functionality to your twill project.
+Packages are a great way to add or create reusable functionality to your Twill project.
 
 At its base, a Twill package is just a Laravel package but starting from the `TwillPackageServiceProvider`.
 
-A package self-registers, and can contain Capsules.
+A package self-registers, and can contain [Capsules](../3_modules/4_capsules.md).
 
-Packages are composer installable.
+Packages are Composer installable.
 
 In the following section we will explain how you can create your own package.