Installation Approachability

bedrock/installation.md

@@ -1,30 +1,18 @@
 ---
-date_modified: 2023-01-27 13:17
+date_modified: 2024-05-22 11:15
 date_published: 2015-10-15 12:29
 description: Installing Bedrock requires PHP 8.0+ and Composer. After setting environment variables and the document root you can access your WordPress installation.
 title: Installing Bedrock
 authors:
   - ben
   - Log1x
   - swalkinshaw
+  - MWDelaney
 ---
 
 # Installation
 
-## What is Bedrock?
-
-Bedrock is a [WordPress boilerplate](https://roots.io/bedrock/).
-
-### Why use Bedrock?
-
-- Better folder structure
-- Dependency management with [Composer](https://getcomposer.org)
-- Easy WordPress configuration with environment specific files
-- Environment variables with [Dotenv](https://github.com/vlucas/phpdotenv)
-- Autoloader for mu-plugins (use regular plugins as mu-plugins)
-- Enhanced security (separated web root and secure passwords with [wp-password-bcrypt](https://github.com/roots/wp-password-bcrypt))
-
-## Requirements
+## System requirements
 
 - PHP >= 8.0
 - [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos)
@@ -34,10 +22,10 @@ Bedrock is a [WordPress boilerplate](https://roots.io/bedrock/).
 Create a new Bedrock project:
 
 ```shell
-$ composer create-project roots/bedrock
+composer create-project roots/bedrock
 ```
 
-## Getting Started
+## Create your `.env` file
 
 - Create a `.env` file with the following environment variables (see `.env.example` as an example):
   - Database variables
@@ -61,5 +49,18 @@ $ composer create-project roots/bedrock
 Bedrock is multisite network compatible, but needs the [roots/multisite-url-fixer](https://github.com/roots/multisite-url-fixer) mu-plugin on subdomain installs to make sure admin URLs function properly. This plugin is not _needed_ on subdirectory installs but will work well with them. From your Bedrock directory:
 
 ```shell
-$ composer require roots/multisite-url-fixer
+composer require roots/multisite-url-fixer
 ```
+
+## What is Bedrock?
+
+Bedrock is a [WordPress boilerplate](https://roots.io/bedrock/).
+
+### Why use Bedrock?
+
+- Better folder structure
+- Dependency management with [Composer](https://getcomposer.org)
+- Easy WordPress configuration with environment specific files
+- Environment variables with [Dotenv](https://github.com/vlucas/phpdotenv)
+- Autoloader for mu-plugins (use regular plugins as mu-plugins)
+- Enhanced security (separated web root and secure passwords with [wp-password-bcrypt](https://github.com/roots/wp-password-bcrypt))

sage/deployment.md

@@ -1,25 +1,19 @@
 ---
-date_modified: 2024-01-18 13:30
+date_modified: 2024-05-22 11:15
 date_published: 2015-09-01 19:29
-description: To deploy a Sage theme you'll need to run `composer install` on the remote server, and copy over theme assets built with `yarn build`.
+description: Compile your assets, install your dependencies, and copy your Sage-based theme to your server. Remember that PHP versions must match between environments.
 title: Deploying Sage
 authors:
   - alwaysblank
   - ben
   - kero
   - Log1x
+  - MWDelaney
 ---
 
 # Deployment
 
-To deploy a Sage theme you'll need to make sure two things are covered:
-
-1. Run `composer install` from the theme directory on the remote server if you have Acorn installed in your theme directory
-2. Copy over built theme assets (the `public/` folder)
-
-Generate production ready assets with `yarn build`.
-
-## Server requirements
+## (Remote) system requirements
 
 - WordPress >= 5.9
 - PHP >= 8.1
@@ -31,6 +25,32 @@ Generate production ready assets with `yarn build`.
 - Tokenizer PHP Extension
 - XML PHP Extension
 
+## Deploying a Sage-based WordPress theme
+
+::: warning PHP versions must match
+Make sure the PHP version of your development environment matches the PHP version of your production environment, or your composer dependencies may not work correctly.
+:::
+
+### 1. Build Assets
+
+Compile your CSS, Javascript, image, and font assets for production:
+
+```shell
+yarn build
+```
+
+### 2. Install Composer dependencies
+
+Install Composer dependencies:
+
+```shell
+composer install
+```
+
+### 3. Copy files to your server
+
+Copy all files and folders in your theme except the `node_modules` directory to your server.
+
 ## Server configuration
 
 ::: tip Using Trellis or Radicle?

sage/installation.md

@@ -1,5 +1,5 @@
 ---
-date_modified: 2023-01-27 13:17
+date_modified: 2024-05-22 11:15
 date_published: 2015-08-29 18:09
 description: Install Sage 10, a WordPress starter theme, by running `composer create-project roots/sage`.
 title: Installing Sage
@@ -11,68 +11,83 @@ authors:
   - Log1x
   - QWp6t
   - TangRufus
+  - MWDelaney
 ---
 
-# Installation
+# Installing Sage
 
 ## What is Sage?
 
 Sage is a [WordPress starter theme](https://roots.io/sage/).
 
-### Why use Sage?
+## Why use Sage?
 
-- Harness the power of [Laravel](https://laravel.com) and its available packages thanks to [Acorn](https://github.com/roots/acorn).
 - Clean, efficient theme templating utilizing [Laravel Blade](https://laravel.com/docs/master/blade).
 - Lightning fast frontend development workflow powered by [Bud](https://bud.js.org/).
 - Out of the box support for [Tailwind CSS](https://tailwindcss.com/).
+- Harness the power of [Laravel](https://laravel.com) and its available packages thanks to [Acorn](https://github.com/roots/acorn).
 
-## Getting Started
+## System Requirements
+
+- [Node.js](https://nodejs.org/)
+- [Composer](https://getcomposer.org/download/)
 
 ::: warning Windows users
-WSL is required in order to use Sage. Build commands must be ran from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/).
+WSL is required in order to use Sage. Build commands must be run from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/).
 :::
 
-Sage relies on Node.js based tools to manage dependencies and build assets. We recommend using [Volta](https://github.com/volta-cli/volta) to install and manage Node.js. We also recommend using [Yarn](https://yarnpkg.com/). [After installing Volta](https://docs.volta.sh/guide/getting-started):
+<!-- For help setting up your development environment, see the [Local Development Environment](/sage/docs/local-development-environment/) guide. -->
 
-```shell
-# Install the latest Node.js LTS release
-$ volta install node
+## Create a new theme with Sage
 
-# Globally install Yarn
-$ npm install --global yarn
+### 1. Create a new Sage-based WordPress theme with Composer
+
+Create a new WordPress theme using Sage with Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme):
+
+```shell
+# From your WordPress themes directory, run:
+composer create-project roots/sage your-theme-name
 ```
 
-## Installing Acorn
+### 2. Edit `bud.config.js` to match your environment
 
-Sage requires Acorn but doesn't ship with it included. This is to give you the flexibility to include it in a way that works best for your environment. There's a few different ways to install Acorn.
+Modify the `bud.config.js` file in your new Sage-based theme's directory to match the theme's directory name and local development URL, if applicable.
 
-See the [Acorn installation](/acorn/docs/installation/) docs for additional details.
+```javascript
+// bud.config.js
 
-## Installing Sage with Composer
+/**
+ * Around line 26, update the following path 
+ * to match your theme's directory:
+*/
 
-Install Sage using Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme):
+app.setPublicPath('/app/themes/sage/public/');
 
-```shell
-# From your WordPress themes directory, run:
-$ composer create-project roots/sage your-theme-name
+/**
+ * Around line 37, pdate the following URL 
+ * to match your local development URL:
+*/
+.setProxyUrl('http://example.test')
 ```
 
-To install the latest development version of Sage, add `dev-main` to the end of the command:
+### 3. Build the theme assets
+
+From your new Sage-based theme's directory, run:
 
 ```shell
-$ composer create-project roots/sage your-theme-name dev-main
+yarn && yarn build
 ```
 
-## Build assets
-
-You must build theme assets in order to access your site. Failing to build the assets will result in the error:
+::: warning You must build theme assets in order to access your site. Failing to build the assets will result in the error:
 
 ```plaintext
 The manifest [/path/to/sage/public/manifest.json] cannot be found.
 ```
 
-### Running the first build
+:::
+
+That's it! You're ready to activate your theme in WordPress and start developing!
+
+## What Next?
 
-- Run `yarn` from the theme directory to install dependencies
-- Update `bud.config.js` with your local dev URL
-- `yarn build` — Compile assets
+From here you might want to [explore the structure of your new Sage-based theme](/sage/docs/theme-structure/), or [learn how to use Blade templates](/sage/docs/blade-templates/), or how to [compile assets](/sage/docs/compiling-assets/). These documents are meant to be referenced as you work with Sage, so feel free to jump around as needed.

sage/structure.md

@@ -1,5 +1,5 @@
 ---
-date_modified: 2023-01-27 13:17
+date_modified: 2024-05-22 11:15
 date_published: 2021-10-21 13:21
 description: The default Sage structure is intended to provide a sane starting point for both small and large WordPress sites alike.
 title: Theme Structure
@@ -8,6 +8,7 @@ authors:
   - ben
   - jure
   - Log1x
+  - MWDelaney
 ---
 
 # Theme Structure
@@ -18,7 +19,7 @@ The default Sage structure is intended to provide a sane starting point for both
 
 Where a file or class is located is ultimately decided by you. As long as Composer can autoload the class or you have modified the necessary paths in your [configuration](configuration.md), things should work as expected.
 
-```php
+```shell
 themes/your-theme-name/   # → Root of your Sage based theme
 ├── app/                  # → Theme PHP
 │   ├── Providers/        # → Service providers
@@ -74,4 +75,3 @@ The `resources` directory contains your Blade views as well as the un-compiled a
 ### The `vendor/` directory
 
 The `vendor` directory contains your [Composer](https://getcomposer.org/) dependencies and autoloader. This directory is automatically generated and should not be modified.
-

sage/tailwind-css.md

@@ -1,10 +1,11 @@
 ---
-date_modified: 2023-03-13 11:00
+date_modified: 2024-05-22 11:15
 date_published: 2023-03-13 11:00
 description: Sage includes Tailwind CSS support, including generating the Tailwind color palette, font families, and sizes for `theme.json` which is used by the block editor.
 title: Tailwind CSS
 authors:
   - ben
+  - MWDelaney
 ---
 
 # Tailwind CSS
@@ -38,74 +39,3 @@ Tailwind’s [default color palette](https://tailwindcss.com/docs/customizing-co
 In addition to including Tailwind’s color palette for the WordPress editor, Sage will also configure the editor with Tailwind’s font families and font sizes.
 
 Be sure to take a look at [Bud’s documentation on this feature](https://bud.js.org/extensions/sage/theme.json/) for further information.
-
-## Using Tailwind's colors from the block editor on the front-end
-
-While Sage makes Tailwind's colors available in the block editor, it doesn't include an approach out of the box for dealing with the front-end styling for the editor classes.
-
-You will need to decide how you want to handle the front-end styling for those classes. For example, you might want to add the following to one of your stylesheets:
-
-```css
-.has-amber-50-background-color {
-  @apply bg-amber-50;
-}
-```
-
-This CSS would allow Tailwind's `amber-50` background color to work when used from the block editor.
-
-### Automating the front-end classes from the editor
-
-If you wanted to automate adding all of the colors, you could use the following example Tailwind plugin:
-
-```javascript
-// Add to the top of your tailwind.config.cjs file
-const plugin = require('tailwindcss/plugin');
-
-// Add the following within your tailwind.config.cjs plugins array:
-plugins: [
-  plugin(function ({addUtilities, theme, variants}) {
-    const colors = theme('colors');
-
-    const colorUtilities = Object.keys(colors).reduce((acc, color) => {
-      if (typeof colors[color] === 'string') {
-        acc[`.has-${color}`] = {
-          'color': colors[color],
-        };
-        acc[`.has-${color}-background-color`] = {
-          'background-color': colors[color],
-        };
-      } else {
-        Object.keys(colors[color]).forEach((shade) => {
-          acc[`.has-${color}-${shade}-background-color`] = {
-            'background-color': colors[color][shade],
-          };
-        });
-      }
-
-      return acc;
-    }, {});
-
-    addUtilities(colorUtilities, variants('backgroundColor'));
-  }),
-],
-```
-
-The biggest issue with this approach is that Tailwind has no insight into which classes have been used from the WordPress editor. If you wanted to allow all of the Tailwind CSS colors to be added to your generated CSS for use in the editor, you could use the [`safelist` option](https://tailwindcss.com/docs/content-configuration#safelisting-classes):
-
-```javascript
-content: ['./index.php', './app/**/*.php', './resources/**/*.{php,vue,js}'],
-// Allow all classes that start with has-
-safelist: [
-  {
-    pattern: /^has-/,
-  }
-],
-```
-
-::: warning Note
-Beware of how large your stylesheets will get if you are using all of the Tailwind CSS colors along with this approach
-:::
-
-The ideal setup is to remove _all_ classes that you aren't using from Tailwind, and only configure Tailwind with the classes that are required for your project.
-
-In the future, we might add a more streamlined approach to doing this to Bud's `theme.json` generator. For now, deciding how you want the front-end CSS to work for Tailwind generated classes is up to you.