24ac51d510
* enhance(project): Add .prettierrc to project * chore(deps): Bump dependencies * chore(view): Improve readability of the search form view * chore(admin): Improve language used in the customize_register filter docblock * chore(lint): Lint project assets * chore(change-log): Improve/prepare the changelog for actual release * chore(readme): Improve README feature list * chore(readme): Update README theme directory structure * chore(readme): Add GitHub sponsors badge * chore(readme): Clean up various wording * fix(ci): Fix failing tests * fix(mix): Add index.php to purgecss scope (Supersedes #2423) (Credit @oxyc)
170 lines
7.5 KiB
Markdown
170 lines
7.5 KiB
Markdown
<p align="center">
|
|
<a href="https://roots.io/sage/">
|
|
<img alt="Sage" src="https://cdn.roots.io/app/uploads/logo-sage.svg" height="100">
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="LICENSE.md">
|
|
<img alt="MIT License" src="https://img.shields.io/github/license/roots/sage?color=%23525ddc&style=flat-square" />
|
|
</a>
|
|
|
|
<a href="https://packagist.org/packages/roots/sage">
|
|
<img alt="Packagist" src="https://img.shields.io/packagist/v/roots/sage.svg?style=flat-square" />
|
|
</a>
|
|
|
|
<a href="https://circleci.com/gh/roots/sage">
|
|
<img alt="Build Status" src="https://img.shields.io/circleci/build/gh/roots/sage?style=flat-square" />
|
|
</a>
|
|
|
|
<a href="https://twitter.com/rootswp">
|
|
<img alt="Follow Roots" src="https://img.shields.io/twitter/follow/rootswp.svg?style=flat-square&color=1da1f2" />
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<strong>WordPress starter theme with a modern development workflow</strong>
|
|
<br />
|
|
Built with ❤️
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://roots.io">Official Website</a> | <a href="https://roots.io/docs/sage/">Documentation</a> | <a href="CHANGELOG.md">Change Log</a>
|
|
</p>
|
|
|
|
## Supporting
|
|
|
|
**Sage** is an open source project and completely free to use.
|
|
|
|
However, the amount of effort needed to maintain and develop new features and products within the Roots ecosystem is not sustainable without proper financial backing. If you have the capability, please consider donating using the links below:
|
|
|
|
<div align="center">
|
|
|
|
[](https://github.com/sponsors/roots)
|
|
[![Sponsor on Patreon](https://img.shields.io/badge/sponsor-patreon-orange.svg?style=flat-square&logo=patreon")](https://www.patreon.com/rootsdev)
|
|
[](https://www.paypal.me/rootsdev)
|
|
|
|
</div>
|
|
|
|
## About Sage
|
|
|
|
Sage is a productivity-driven WordPress starter theme with a modern development workflow.
|
|
|
|
**The `master` branch currently tracks Sage 10 which is in active development. Looking for Sage 9? [See releases](https://github.com/roots/sage/releases).**
|
|
|
|
## Features
|
|
|
|
- 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/latest/blade).
|
|
- Easy [Browsersync](http://www.browsersync.io/) support alongside asset compilation, concatenating, and minification powered by [Laravel Mix](https://github.com/JeffreyWay/laravel-mix).
|
|
- Out of the box support for [Bootstrap 5](https://getbootstrap.com/) and [jQuery](https://jquery.com).
|
|
- A clean starting point for theme styles using [Sass](https://sass-lang.com/).
|
|
|
|
See a working example at [roots-example-project.com](https://roots-example-project.com/).
|
|
|
|
## Requirements
|
|
|
|
Make sure all dependencies have been installed before moving on:
|
|
|
|
- [WordPress](https://wordpress.org/) >= 5.4
|
|
- [PHP](https://secure.php.net/manual/en/install.php) >= 7.2.5 (with [`php-mbstring`](https://secure.php.net/manual/en/book.mbstring.php) enabled)
|
|
- [Composer](https://getcomposer.org/download/)
|
|
- [Node.js](http://nodejs.org/) >= 12.0.0
|
|
- [Yarn](https://yarnpkg.com/en/docs/install)
|
|
|
|
## Theme installation
|
|
|
|
Install Sage using Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme):
|
|
|
|
```sh
|
|
# @ app/themes/ or wp-content/themes/
|
|
$ composer create-project roots/sage your-theme-name
|
|
```
|
|
|
|
To install the latest development version of Sage, add `dev-master` to the end of the command:
|
|
|
|
```sh
|
|
$ composer create-project roots/sage your-theme-name dev-master
|
|
```
|
|
|
|
## Theme structure
|
|
|
|
```sh
|
|
themes/your-theme-name/ # → Root of your Sage based theme
|
|
├── app/ # → Theme PHP
|
|
│ ├── View/ # → View models
|
|
│ ├── Providers/ # → Service providers
|
|
│ ├── admin.php # → Theme customizer setup
|
|
│ ├── filters.php # → Theme filters
|
|
│ ├── helpers.php # → Helper functions
|
|
│ └── setup.php # → Theme setup
|
|
├── config/ # → Config files
|
|
│ ├── app.php # → Application configuration
|
|
│ ├── assets.php # → Asset configuration
|
|
│ ├── filesystems.php # → Filesystems configuration
|
|
│ ├── logging.php # → Logging configuration
|
|
│ └── view.php # → View configuration
|
|
├── composer.json # → Autoloading for `app/` files
|
|
├── composer.lock # → Composer lock file (never edit)
|
|
├── dist/ # → Built theme assets (never edit)
|
|
├── functions.php # → Theme bootloader
|
|
├── index.php # → Theme template wrapper
|
|
├── node_modules/ # → Node.js packages (never edit)
|
|
├── package.json # → Node.js dependencies and scripts
|
|
├── resources/ # → Theme assets and templates
|
|
│ ├── assets/ # → Front-end assets
|
|
│ │ ├── fonts/ # → Theme fonts
|
|
│ │ ├── images/ # → Theme images
|
|
│ │ ├── scripts/ # → Theme javascript
|
|
│ │ └── styles/ # → Theme stylesheets
|
|
│ └── views/ # → Theme templates
|
|
│ ├── components/ # → Component templates
|
|
│ ├── form/ # → Form templates
|
|
│ ├── layouts/ # → Base templates
|
|
│ └── partials/ # → Partial templates
|
|
├── screenshot.png # → Theme screenshot for WP admin
|
|
├── storage/ # → Storage location for cache (never edit)
|
|
├── style.css # → Theme meta information
|
|
├── vendor/ # → Composer packages (never edit)
|
|
└── webpack.mix.js # → Laravel Mix configuration
|
|
```
|
|
|
|
## Theme setup
|
|
|
|
Edit `app/setup.php` to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.
|
|
|
|
## Theme development
|
|
|
|
- Run `yarn` from the theme directory to install dependencies
|
|
- Update `webpack.mix.js` with your local dev URL
|
|
|
|
### Build commands
|
|
|
|
- `yarn start` — Compile assets when file changes are made, start Browsersync session
|
|
- `yarn build` — Compile and optimize the files in your assets directory
|
|
- `yarn build:production` — Compile assets for production
|
|
|
|
## Documentation
|
|
|
|
- [Sage documentation](https://roots.io/sage/docs/)
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome from everyone. We have [contributing guidelines](https://github.com/roots/guidelines/blob/master/CONTRIBUTING.md) to help you get started.
|
|
|
|
## Sage sponsors
|
|
|
|
Help support our open-source development efforts by [becoming a sponsor](https://github.com/sponsors/roots).
|
|
|
|
<a href="https://kinsta.com/?kaid=OFDHAJIXUDIV"><img src="https://cdn.roots.io/app/uploads/kinsta.svg" alt="Kinsta" width="200" height="150"></a> <a href="https://k-m.com/"><img src="https://cdn.roots.io/app/uploads/km-digital.svg" alt="KM Digital" width="200" height="150"></a> <a href="https://carrot.com/"><img src="https://cdn.roots.io/app/uploads/carrot.svg" alt="Carrot" width="200" height="150"></a>
|
|
|
|
## Community
|
|
|
|
Keep track of development and community news.
|
|
|
|
- Participate on the [Roots Discourse](https://discourse.roots.io/)
|
|
- Follow [@rootswp on Twitter](https://twitter.com/rootswp)
|
|
- Read and subscribe to the [Roots Blog](https://roots.io/blog/)
|
|
- Subscribe to the [Roots Newsletter](https://roots.io/subscribe/)
|
|
- Listen to the [Roots Radio podcast](https://roots.io/podcast/)
|