📝 Radicle docs

roots · Apr 3, 2023 · f0d3ebf · f0d3ebf
1 parent e48e4d3
commit f0d3ebf
Show file tree

Hide file tree

Showing 11 changed files with 361 additions and 0 deletions.
diff --git a/radicle/adding-routes.md b/radicle/adding-routes.md
@@ -0,0 +1,44 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Adding Routes
+authors:
+  - ben
+---
+
+# Adding Routes
+
+Radicle uses Acorn which allows you to register Laravel routes from the `config/web.php` file.
+
+By default, a route is registered for `/welcome/` which serves the Blade template located at `resources/views/welcome.blade.php`.
+
+See [Laravel's routing documentation](https://laravel.com/docs/9.x/routing) for information on registering routes.
+
+::: tip
+Acorn's router support is still considered experimental due to limited support of Laravel's router functionality. Once Acorn supports [modifying the current kernel implementation](https://github.com/roots/acorn/issues/276), Radicle will include the default Laravel HTTP kernel along with an example of implementing a route with middleware support.
+:::
+
+Since routes in Radicle are considered "virtual pages", WordPress is not aware of how to handle some functionality such as:
+
+* Setting the canonical URL
+* Setting the `<title>`
+* Adding SEO-related meta data
+
+Make sure to take this into consideration when adding routes to your site. Acorn's router implementation currently contains a `acorn/router/do_parse_request` filter that can be used as a way to communicate data from a Laravel route to WordPress.
+
+In the example below, we're setting the `is_acorn_route` property of the `$wp_query` object to true for any pages that are Acorn routes:
+
+```php
+<?php
+
+add_filter('acorn/router/do_parse_request', function ($do_parse) {
+    global $wp_query;
+    $wp_query->is_acorn_route = true;
+
+    return $do_parse;
+});
+```
+
+::: tip
+The Radicle roadmap includes plans for adding better SEO support to Laravel routes that integrates them with Yoast and The SEO Framework. This functionality will be packaged as a Composer dependency that's separate from Radicle.
+:::
diff --git a/radicle/block-editor-plugins.md b/radicle/block-editor-plugins.md
@@ -0,0 +1,27 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Block Editor Plugins
+authors:
+  - ben
+---
+
+# Block Editor Plugins
+
+Editor plugins are used for most editor functionality that aren't directly related to a custom block.
+
+::: tip
+The Radicle roadmap includes more editor examples for both blocks and editor plugins
+:::
+
+## Asset locations
+
+Block editor plugins live in the `resources/scripts/editor/` directory.
+
+They are automatically registered from `radicle/resources/scripts/editor.ts`.
+
+Radicle uses the [`@roots/bud-preset-wordpress` extension from bud.js](https://bud.js.org/extensions/bud-preset-wordpress/editor-integration) for registering block plugins.
+
+## Default editor plugin
+
+By default, Radicle ships with an example editor plugin (`example.plugin.tsx`) that unregisters all blocks that aren't in the text or media categories.
diff --git a/radicle/blocks.md b/radicle/blocks.md
@@ -0,0 +1,27 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Blocks
+authors:
+  - ben
+---
+
+# Blocks
+
+Radicle comes with a basic block example to demonstrate where to register blocks on your site.
+
+::: tip
+The Radicle roadmap includes more editor examples for both blocks and editor plugins
+:::
+
+If you are building a block that will be used across multiple projects/sites, we recommend building them as separate packages/plugins. If you are building a block that is specific to your Radicle-based site, then we recommend getting started with the example block that's included in Radicle.
+
+While it's usually recommended to build editor functionality separate from your WordPress theme, Radicle blurs the lines of what a WordPress theme is — you will never need to edit anything from the theme directory (`public/content/themes/radicle/`).
+
+## Asset locations
+
+Blocks live in the `resources/scripts/editor/` directory.
+
+They are automatically registered from `radicle/resources/scripts/editor.ts`.
+
+Radicle uses the [`@roots/bud-preset-wordpress` extension from bud.js](https://bud.js.org/extensions/bud-preset-wordpress/editor-integration) for registering blocks.
diff --git a/radicle/deployment.md b/radicle/deployment.md
@@ -0,0 +1,24 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Deploying Radicle
+authors:
+  - ben
+---
+
+# Deployment
+
+You will need to make sure that your deployment process handles the following:
+
+1. Run `yarn && yarn build` from the project root
+1. Copy contents of `public/dist/` folder to your server (produced from `yarn build`)
+1. Run `wp acorn optimize`
+1. Run `wp acorn icons:cache` (if using Blade Icons)
+1. Run `wp login install --activate` (if wanting to use the WP-CLI login command)
+
+## Deploying with Trellis
+
+If you choose to use Trellis for handling your deployments, there are two options:
+
+1. Use GitHub Actions with [setup-trellis-cli](https://github.com/roots/setup-trellis-cli) — uncomment the deploy job from `.github/workflows/deploy.yml`. It is configured to deploy to the production environment on every push to the `main` branch
+1. Run `trellis deploy <environment>`
diff --git a/radicle/installation.md b/radicle/installation.md
@@ -0,0 +1,50 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Installing Radicle
+authors:
+  - ben
+---
+
+# Installation
+
+## What is Radicle?
+
+[Radicle](/radicle/) is an opinionated starting point for WordPress projects with the Roots stack.
+
+Radicle includes the preferred setup of Acorn, Bedrock, Bud, Sage, and Trellis from the creators of Roots.
+
+### Why use Radicle?
+
+The Roots ecosystem contains several projects and most of them are built in a way where they don't require one another. There are some exceptions to this: Sage requires Acorn and Trellis requires Bedrock.
+
+Our WordPress starter theme, Sage, is distributed in a way that is compatible with every type of WordPress setup. Since Sage 10 and the introduction of Acorn, which allows developers to use Laravel components within WordPress, it hasn't been possible for us to easily distribute the theme with our ideal setup because it requires changes made outside of the typical `wp-content` directory.
+
+Since the release of Acorn, we've preferred to use a more [traditional Laravel-esque structure](https://roots.io/acorn/docs/directory-structure/) from the root of the project. We've made the root of the project the area of focus, including everything related to the WordPress theme, which is a modified verison of Sage 10. All of your theme templates are located at `resources/views/`. No more navigating 7 levels deep to get to your templates — they're just 2 levels away.
+
+[**See the full list of Radicle features**](/radicle/#features)
+
+## Server requirements
+
+* Your document root must be configurable (_most_ local development tools and webhosts should support this)
+* PHP >= 8.0 with the following extensions: BCMath, Ctype, Fileinfo, JSON, Mbstring, Tokenizer, XML
+* Composer
+* WP-CLI
+
+## Installing Radicle
+
+Radicle requires [purchasing a Radicle license](/radicle/) to get access to the codebase. Once Radicle has been purchased, you can use the [Roots Dashboard](https://dashboard.roots.io/) to generate an invitation to the GitHub repository or download the latest release.
+
+After you've accepted the invitation to the GitHub repository, navigate to the [releases to download the latest version of Radicle](https://github.com/roots/radicle/releases).
+
+::: tip
+Are you building new sites often? Create your own private repo with the Radicle codebase and modify it to fit your needs. Radicle should be treated as a boilerplate/starting point, and not a framework.
+:::
+
+::: tip
+The Radicle roadmap includes plans for adding better SEO support to Laravel routes that integrates them with Yoast and The SEO Framework. This functionality will be packaged as a Composer dependency that's separate from Radicle.
+:::
+
+Although it is possible to retrofit an existing project with Radicle, we recommend using Radicle on a new project.
+
+Unzip the contents of the latest Radicle release into your new project's directory. Make sure all of the hidden files (such as `.gitignore`) are included in your project directory.
diff --git a/radicle/local-development.md b/radicle/local-development.md
@@ -0,0 +1,51 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Local Development
+authors:
+  - ben
+---
+
+# Local Development
+
+Radicle comes with configuration for two local development setups out of the box:
+
+* [Lando](https://lando.dev/)
+* [Trellis](https://roots.io/trellis/)
+
+Neither of these are a requirement, and any local development tool can be used with Radicle as long as you set your document root to the `public` directory. You will also need to:
+
+1. Run `yarn && yarn build`
+1. Run `composer install`
+1. Copy `.env.example` to `.env` and update the [environment variables](https://roots.io/bedrock/docs/installation/#getting-started)
+
+## Lando
+
+To use Lando with Radicle:
+
+1. In `bud.config.js`: Replace `http://radicle.test` with `https://radicle.lndo.site`
+1. Run `yarn && yarn build`
+1. Run `lando start`
+1. Visit `https://radicle.lndo.site/`
+
+You can run `lando login` to generate a passwordless wp-admin login URL (WordPress must first be installed).
+
+## Trellis
+
+Run `php .radicle-setup/trellis.php` to grab the latest version of Trellis and apply the necessary modifications for Radicle. After you've ran this script,
+navigate to the Trellis directory to init and start your project:
+
+```shell
+$ php .radicle-setup/trellis.php
+$ cd trellis/
+$ trellis init
+$ trellis up
+```
+
+Open `bud.config.js` and replace `http://radicle.test` with your local development URL. For example, if you used `example.com` as the domain name during the setup then your URL would be `http://example.test`. If you are unsure what this URL is, open `trellis/group_vars/development/wordpress_sites.yml` and use the canonical URL.
+
+Then you will want to run `yarn && yarn build` before visiting your site at `http://example.test/`.
+
+You can remove the `.radicle-setup/` directory after you've ran the Trellis script, or if you aren't planning to use Trellis.
+
+Make sure to commit the changes to the repo as there will now be a `trellis/` folder.
diff --git a/radicle/registering-post-types.md b/radicle/registering-post-types.md
@@ -0,0 +1,45 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Registering Post Types
+authors:
+  - ben
+---
+
+# Registering Post Types
+
+The `config/post-types.php` file is used to register custom post types.
+
+Radicle includes the [Extended CPTs](https://github.com/johnbillion/extended-cpts) library along with a post types service provider to allow for configuring post types from a config.
+
+By default, a `seed` post type is registered. Remove or replace this post type with one that works for your site.
+
+All of the [parameters from Extended CPTs](https://github.com/johnbillion/extended-cpts/wiki/Registering-Post-Types) are supported, and the example post type included in Radicle shows how to override the names used for the `singular`, `plural`, and `slug`.
+
+## Registering multiple post types
+
+In `config/post-types.php` within the `post_types` array, add additional array keys to register multiple post types. In the example below, we are registering two post types: `seed` and `product`.
+
+```php
+<?php
+
+return [
+    'post_types' => [
+        'seed' => [
+            'menu_icon' => 'dashicons-star-filled',
+            'supports' => ['title', 'editor', 'author', 'revisions', 'thumbnail'],
+            'show_in_rest' => true,
+            'names' => [
+                'singular' => 'Seed',
+                'plural' => 'Seeds',
+                'slug' => 'seeds',
+            ]
+        ],
+        'product' => [
+            'menu_icon' => 'dashicons-cart',
+            'supports' => ['title', 'editor', 'author', 'revisions', 'thumbnail'],
+            'show_in_rest' => true,
+        ],
+    ],
+];
+```
diff --git a/radicle/registering-taxonomies.md b/radicle/registering-taxonomies.md
@@ -0,0 +1,15 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Registering Taxonomies
+authors:
+  - ben
+---
+
+# Registering Taxonomies
+
+Similar to [registering post types](/radicle/docs/registering-post-types/), Radicle uses the [Extended CPTs](https://github.com/johnbillion/extended-cpts) library along with a post types service provider to allow for configuring taxonomies from a config.
+
+By default, a `seed_category` taxonomy is registered and associated with the `seed` post type. Remove or replace this taxonomy with one that works for your site.
+
+All of the [parameters from Extended CPTs](https://github.com/johnbillion/extended-cpts/wiki/Registering-taxonomies) are supported.
diff --git a/radicle/service-provider-configuration.md b/radicle/service-provider-configuration.md
@@ -0,0 +1,34 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Service Provider Configuration
+authors:
+  - ben
+---
+
+# Service Provider Configuration
+
+Radicle comes with three service providers out of the box:
+
+* `AssetsServiceProvider` — Used for WordPress assets (CSS and JS) registration 
+* `PostTypesServiceProvider` — Used for post type and taxonomy registration from a cnfig
+* `ThemeServiceProvider` — Used for registering [theme supports](https://developer.wordpress.org/reference/functions/add_theme_support/) and sidebars from a config
+
+These service providers are loaded from the `composer.json` file:
+
+```json
+...
+    "extra": {
+        "acorn": {
+            "providers": [
+                "App\\Providers\\AssetsServiceProvider",
+                "App\\Providers\\ThemeServiceProvider",
+                "App\\Providers\\PostTypesServiceProvider"
+            ]
+        },
+...
+```
+
+You can add/modify/remove these service providers. If adding or removing providers, we recommend changing the `composer.json` file.
+
+It is also possible to use the `config/app.php` file and modify the `providers` array to manage autoloaded service providers.
diff --git a/radicle/support.md b/radicle/support.md
@@ -0,0 +1,17 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Radicle Support
+authors:
+  - ben
+---
+
+# Support
+
+While we strive to help our customers in any way we can, a Radicle license doesn't cover the Roots team troubleshooting any application code issues that aren't directly related to Radicle itself.
+
+## Bug reports, feature requests, and feedback
+
+If you discover a bug in Radicle, please make a topic on [Roots Discourse](https://discourse.roots.io/c/radicle) with minimal reproduction instructions.
+
+If you have feature requests, questions, or feedback, please make a topic on [Roots Discourse](https://discourse.roots.io/c/radicle) or use the #radicle channel on our Discord server.
diff --git a/radicle/theme-configuration.md b/radicle/theme-configuration.md
@@ -0,0 +1,27 @@
+---
+date_modified: 2023-03-28 07:00
+date_published: 2023-03-28 07:00
+title: Theme Configuration
+authors:
+  - ben
+---
+
+# Theme Configuration Basics
+
+The `config/theme.php` file should be used to configure:
+
+* Navigation menus
+* Sidebars
+* Theme supports
+
+::: tip
+Coming from a typical Sage setup? This file replaces `app/setup.php`
+:::
+
+The Bud config (`bud.config.js`) is used for configuring the `theme.json` file that is used by the WordPress editor. For further information on `theme.json` and Bud's generator for it, see:
+
+* [https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/)
+* [https://bud.js.org/extensions/sage/theme.json](https://bud.js.org/extensions/sage/theme.json)
+* [https://roots.io/sage/docs/tailwind-css/](https://roots.io/sage/docs/tailwind-css/)
+
+You will never need to edit anything from the theme directory (`public/content/themes/radicle/`) unless you want to change the name of the theme from Radicle.