diff --git a/sage/deployment.md b/sage/deployment.md index 3597a7f9..20472890 100644 --- a/sage/deployment.md +++ b/sage/deployment.md @@ -1,35 +1,35 @@ --- -date_modified: 2024-01-18 13:30 +date_modified: 2024-06-04 16:00 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: +::: warning PHP versions must match +Make sure the PHP version of your development environment matches the PHP version of your production environment, or you may hit a fatal error due to your Composer dependencies requiring a different PHP version. +::: + +## Deploying a Sage-based WordPress theme -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) +1. Build theme assets (`yarn build`) +2. Install Composer dependencies (`composer install --no-dev --optimize-autoloader`) +3. Upload all files and folders in your theme except the `node_modules` directory to your host -Generate production ready assets with `yarn build`. +## Optimization -## Server requirements +Similar to deploying a Laravel app, Acorn supports an `optimize` command that will cache your configuration and views. This command should be ran as part of your deployment process: -- WordPress >= 5.9 -- PHP >= 8.1 -- BCMath PHP Extension -- Ctype PHP Extension -- Fileinfo PHP Extension -- JSON PHP Extension -- Mbstring PHP Extension -- Tokenizer PHP Extension -- XML PHP Extension +```shell +wp acorn optimize +``` ## Server configuration @@ -86,9 +86,3 @@ If you use [Trellis](https://roots.io/trellis/), you can build your assets local ## Deploying Sage on WP Engine See the instructions from [`wpengine/example-sage-theme`](https://github.com/wpengine/example-sage-theme). - -## Deploying Sage via FTP - -If you don't have permission to run `composer` on the production server and/or are using a shared hosting service, you may want to deploy Sage with FTP. -To do so, [compile your assets for production](compiling-assets.md) and run `composer install --no-dev` in your theme directory. -Upload all files and folders in your theme except the `node_modules` directory to your host. diff --git a/sage/structure.md b/sage/structure.md index 3866d172..c4d92973 100644 --- a/sage/structure.md +++ b/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. - diff --git a/sage/tailwind-css.md b/sage/tailwind-css.md index df954a2c..8d701421 100644 --- a/sage/tailwind-css.md +++ b/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.