💨 WordPress starter theme - designed to be minimal, ultra-lightweight (< 20 kB) and easy for all kinds of WordPress projects. 7+years/1000+hours of development and still updating daily! We prefer the original WordPress way of doing things so no strange templating languages or frameworks here.
MIT License
Air-light (or simply Air) is designed to be an ultra minimal starting point for a WordPress project at Digitoimisto Dude Oy, a Finnish boutique digital agency in the center of Jyvskyl. Theme is originally based on _s. We welcome all happy contributors with open arms! See roadmap.
This theme is constantly kept up to date by a bunch of awesome contributors. Wanna join in development? Read the instructions for contributing and let us know about your first PR!
Air-light is built to be very straightforward, backwards compatible, front-end developer friendly and modular by its structure. Following Underscores and WordPress Theme Coding Standards best practices and most of the changes in _s are implemented as soon as they are committed.
Our mission and goal is minimalism and simplicity. Our vision is to build a theme that will not implement its own wrappers or functions, will not use any templating languages that would take things further from traditional PHP or CSS, will contain nothing that people will not use or need. Air-light will be free of weird "app-like" folder structures or odd syntaxes that nobody else uses. We love WordPress as it was and as it is.
Air was renamed to air-light in version 3.7.8 (March 20th, 2018), because air was already taken in the official WordPress theme directory.
Air-light v. 4.2.2 was approved to official WordPress theme directory on June 4, 2018. But please note, all changes you do to the theme without generating your own or changing textdomain will be overridden in theme updates - so if you use this theme as a starting point, please follow instructions and/or replace the textdomain with your own.
Air is a development theme, so it has updates very often. By using this starter theme, you agree that anything can change to a different direction without a warning when you look at this dev-git the next time. Please note this theme has no updates inside WordPress by design. Use this theme to hack it to pieces and create your new awesome theme based on Air! Please also see Debuggers!
Air is not meant to be "a theme for everyone", which means it doesn't have all the parts that are generally included in multi-purpose themes for non-technical people (please see Disabled features).
If you want to use this theme as starter for your new theme, please note the theme won't necessarily be that much fun or won't look good by default and needs work from you. We recommend using Sage if you need something more extended.
Air is licensed with The MIT License (MIT) which means you can freely use this theme commercially or privately, modify it, or distribute it, but you are forbidden to hold Dude liable for anything, or claim that what you do with this is made by us.
We try to follow traditional WordPress Template Hierarchy as much as possible. This way we will provide a low threshold for junior developers and go hand in hand with official WordPress Theme Coding Standards.
Please see Visual Overview if you are interested in how the WordPress theme structure works.
Some features, WooCommerce support and personal preferences of Dude are moved to Air helper plugin.
@include responsive-font($font-size-min, $font-size-max);
(formerly Megatype, still recommended with blogs or text-only based sites, but not included by default after 1.5.0)fonts/
directory, you'll need .odt, .ttf, .woff, .woff2. Then just @include fontFace('Proxima Nova', '../../fonts/proximanova-regular-webfont', 400);
in _typography.scss.Air-light can register your CPT:s automatically.
functions.php
like this:'post_types' => [
'Your_Post_Type'
]
inc/post-types/your-post-type.php
Post_Type
class with Your_Post_Type
and define your post type in a public function called register()
. See the example: inc/post-types/your-post-type.php
.Air-light can register your Taxonomies automatically.
functions.php
like this:'taxonomies' => [
'Your_Taxonomy' => [ 'post', 'page', 'your-post-type' ]
]
inc/taxonomies/your-taxonomy.php
Taxonomy
class with Your_Taxonomy
and define your taxonomy in a public function called register()
. See the example: inc/taxonomies/your-taxonomy.php
.Air-light uses namespaced PHP since 5.0.0. This means that we no longer need to prefix functions and hooks, because namespace Air_Light;
takes care of that.
When old function format was:
// Pre_get_posts
add_action( 'pre_get_posts', 'dude_pre_get_posts' );
function dude_pre_get_posts( $query ) {
// Do something
}
New format goes like this:
// Pre_get_posts
add_action( 'pre_get_posts', __NAMESPACE__ . '\pre_get_posts' );
function pre_get_posts( $query ) {
// Do something
}
Creating accessible websites is really important and our goal is to make air as accessible-ready as possible. Theme fully supports navigating with keyboard and screen-readers. Other accessible features:
From 4.7.1 air-light has a lazy loading image features for background images and imgs. If you don't use this feature, remove it from scripts. This feature depends on air-helper, check out the documentation in air-helper for further instructions.
All .js files in /js/src/*
is built to production bundles in /js/prod/
folder and development bundles in /js/dev/
folder with the same name and loaded corresponding to the WP_ENV environment variable. The production scripts can be loaded on development by using ?load_production_builds
URL parameter. The main scripts file loaded in front end is /js/src/front-end.js
.
If you want to add a piece of custom JS, create a file under /js/src/modules/
and import or require it in /js/src/front-end.js
. If you need a admin-specific JS, add a /js/src/admin.js
and then enqueue /js/dist/admin.js
with enqueue_admin_scripts
Our build uses babel to translate scripts to ES2015 compatible JS, so you can use modern JS syntax without thinking about backwards compatibility. There is a /js/src/legacy.js
file, which contains the needed polyfills for browsers not supporting the ES2015 syntax and is automatically loaded on the header when such browser is detected.
We use Airbnb es-lint presets spiced up with our own flavors.
Air has a sticky navigation baked in.
You can enable the sticky navigation by uncommenting navSticky() in the js/src/front-end.js file.
Air had by default a basic WooCommerce support from version 1.9.2, and for a while it was been separated to its own repository, air-woocommerce since v2.5.6.
Starting from v2.6.0 WooCommerce support comes with Air helper plugin and Air contains optional very basic WC styles. Air helper will add it's WC functionality when theme support for WooCommerce is added. To enable:
Please refer to Wiki section Getting started in theming with Air-light.
See Documentation.
If you have ideas about the theme or spot an issue, please let us know. Before contributing ideas or reporting an issue about "missing" features or things regarding to the nature of that matter, please read Please note section. Thank you very much.
If you want to contribute to the development, please follow these instructions:
If you want to improve air, you have two options.
Air is originally built on dudestack. Install our development environment with these steps (unix only, sorry Windows!):
mkdir -p /var/www && cd /var/www/ && git clone https://github.com/digitoimistodude/dudestack
cd /var/www/dudestack/bin
and run bash wsl.sh
or bash macos.sh
depending on your platform. Follow instructions.createproject
, name project after airdev when askedcd /var/www/airdev/content/themes
)git clone [email protected]:yourusername/air-light.git
(replace yourusername
with your actual username)cd /var/www/airdev/content/themes/air-light
devDependencies
to package.json from here
npm install
inside the theme folder (if you don't have npm installed, see here or just use homebrew)cd /var/www/airdev && vendor/wp-cli/wp-cli/bin/wp theme activate air-light
code /var/www/airdev/content/themes/air-light
or via GUI (Open folder).cd /var/www/airdev/content/themes/air-light
and then run gulp
and start developing! Please note, contributing to this theme is only possible when gulp is run from theme directory, NOT on project root.You may want to add alias wp='./vendor/wp-cli/wp-cli/bin/wp'
for macos-lemp-setup to be able to run WP-CLI with just wp
.
To install air-light to your own development environment, just clone your fork to your theme directory, activate the theme, and make changes. If you make changes to front-end (JS/SCSS), you'll need to use our gulpfile and npm dependencies, so make sure you go through steps 9-10 and 12 above.
When you make changes, commit them with clear describing commit messages and them make a pull request. We are happy to accept improvements!
Next you just need to add content and menu via airdev.test/admin, or you can use the ready-made content:
cd ~/Projects/airdev
wp plugin install wordpress-importer --activate
wget https://wpcom-themes.svn.automattic.com/demo/theme-unit-test-data.xml
wp import theme-unit-test-data.xml --authors=create
Air-light comes with PHP_CodeSniffer for PHP files, stylelint for SCSS/CSS files and eslint for JS files built inside gulpfile.js. Please note, you need to configure global versions of these separately!
It's also recommended to use Query Monitor plugin, as some debugging messages goes straight to it's logger.
PHP_CodeSniffer needs to be installed under /usr/local/bin/phpcs
with WordPress-Coding-Standards for php-debuggers to work properly in gulp. If you don't want to use phpcs with gulp, you can disable it by commenting out or deleting line gulp.watch(phpSrc, ['phpcs']);
.
The golden rule here is to make sure the commands stylelint
, eslint
and phpcs
work from command line.
This tutorial is based on the official instructions in WordPress-Coding-Standards and can be found also in our Internal handbook How to install the latest PHP_CodeSniffers with latest WordPress-Coding-Standards (private)
First, remove the old phpcs installation if you have one:
sudo rm /usr/local/bin/phpcs
Then go to home (not really yet, just on your command line, lol):
cd $HOME
Then, install phpcs + WPCS via composer:
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev wp-coding-standards/wpcs:"^3.0"
Symlink globally:
sudo ln -s $HOME/.composer/vendor/bin/phpcs /usr/local/bin/phpcs
sudo chmod +x /usr/local/bin/phpcs
Get PHPCompatibility package:
composer global require --dev phpcompatibility/php-compatibility:"*"
Test it works:
phpcs -i
Output should read:
The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, PHPCompatibility, Modernize, NormalizedArrays, Universal, PHPCSUtils, WordPress, WordPress-Core, WordPress-Docs and WordPress-Extra
Check that other linters work: stylelint -v
, eslint -v
It's also best to have all stylelint
, eslint
, phpcs
living inside your editor. We think Visual Studio Code is best for this, check out the plugins inside vscode-settings repository to make sure everything is installed.
This release cycle will release a new version to:
Whenever you have updates that are worthwhile, commit them with clear commit messages and then do versioning. Every meaningful commit or bunch of commits that form a feature together make the version go up semantically 0.0.1.
Use bash alias (replace YOURUSERNAME with your own):
alias release_new_air_version='git push && git push --tags && rsync -av -e ssh --exclude={"/node_modules/*","/bin/*","/sass/*"} /var/www/airdev/content/themes/air-light/* YOURUSERNAME@YOURSERVER:/var/www/airwptheme.com/public_html/demo/content/themes/air-light/ && /var/www/airdev/content/themes/air-light/bin && sh air-move-out.sh && sh air-pack.sh'
The release cycle:
git tag -a x.x.x
commands, add the same description than in CHANGELOG.mdrelease_new_air_version
(this will move dotfiles etc. out, take care of packing and will give the URL for uploading to WordPress.org)sh air-move-in.sh
. This will move dev-version back and restore the git functionality.That's it, you released a new version!
Gzip file sizes tested with wc -c css/prod/global.css
and gzip -c css/prod/global.css | wc -c
commands.
Theme developers please note: if you use phpcs in SublimeLinter as custom standard on dudestack, you will need extra content/themes/air-light subfolders inside the theme directory for it to work on both global projects and with air-light.
See tool related issues in devpackages and air-light issue tracker.