Oxygen Theme

Oxygen by kittyfishfrommars is a continuation of hughbris work for Grav CMS.

Demo: kittyfishfrommars.github.io

All-in-one package: grav-skeleton-oxygen

Table of Contents

• Summary
• Installation
  • GPM Installation (Preferred)
  • Manual Installation
  • Setup
• Updating
  • GPM Update (Preferred)
  • Manual Update
• Supported Templates
• Configuration
  • Theme Options
  • Page Options
  • Environments
• Build Tools
  • Gulp
• Troubleshooting
  • 500 Internal Server Error
• Examples in the wild
• Credits

Summary

Please see CHANGELOG.md for a detailed list of features included in this release.

• Oxygen is screen-reader friendly and meets Accessibility standards
• Asset delivery has been optimized for Performance
• Grav's admin plugin is supported via blueprints for ease of Maintenance
• Preconfigured to set no cookies, no third-party connections for GDPR-compliance

This theme includes a legally required Contact page, with mandatory data pre-filled, to help with GDPR and Press Regulations. Please make sure to update your personal data and privacy statement to your specific use case. National laws apply.

There's an additional Elements page included to allow you to identify gaps in the theme's styling. There are a few.

Installation

GPM Installation (Preferred)

The simplest way to install this theme is via the Grav Package Manager (GPM) through your system's Terminal (also called the command line). From the root of your Grav install type:

bin/gpm install oxygen

This will install the theme into your /user/themes directory within Grav. Its files can be found under user/themes/oxygen.

This method will copy the sample pages provided in the _demo/pages folder to your user/pages folder so that the theme will work out of the box with placeholder content.

Manual Installation

Please note that the demo content and configuration is not copied when your plugin or theme is installed via the Admin plugin. Please refer the provided files from the _demo folder.

To install this theme, download the zip version of this repository and unzip it under user/themes. Then, rename the folder to oxygen. You can find these files either on GitHub or via GetGrav.org.

You should now have all the theme files under

user/themes/oxygen

It's easiest to adapt the default configuration and content provided with the original theme: move the contents of _demo into your grav installations's user/pages directory to ensure that the theme templates work out of the box.

Setup

If you want to set Oxygen as the default theme, you can do so by following these steps:

• Navigate to grav/user/config.
• Open the system.yaml file.
• Change the theme: setting to theme: oxygen and save your changes.
• Open the site.yaml file.
• Add this line at the bottom: taxonomies: [tag] and save your changes.
• Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in Terminal and typing bin/grav clear-cache.

Once this is done, you should be able to see the new theme on the frontend. Keep in mind any customizations made to the previous theme will not be reflected as all of the theme and templating information is now being pulled from the oxygen folder.

Updating

As development for the Oxygen theme continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating Oxygen is easy, and can be done through Grav's GPM system, as well as manually.

GPM Update (Preferred)

The simplest way to update this theme is via the Grav Package Manager (GPM). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:

bin/gpm update oxygen

This command will check your Grav install to see if your theme is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type y and hit enter. The theme will automatically update and clear Grav's cache.

Manual Update

Manually updating this theme is pretty simple. Here is what you will need to do to get this done:

• Delete the user/themes/oxygen directory.
• Download the new version of the oxygen theme from either GitHub or GetGrav.org.
• Unzip the zip file in user/themes and rename the resulting folder to oxygen.
• Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing bin/grav clear-cache.

Note: Please backup any changes you have made to any of the files. Files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in user/config/themes) will remain intact.

Supported Templates

• Sample home template
• Default content template
• Sidebar template
• Link module
• Footer template
• Error template
• Sitemap template

Configuration

Theme Options

Enable site-wide indexing

For a granular approach to indexing per page, please refer to Grav's [#page-options].

By default Oxygen additionally instructs search engines to not index any content, so you can setup your new site in your own time. Once you are ready to go live you have two ways to remove the noindex meta tag:

Method 1: Admin Panel

Enable indexing through the Grav Admin Panel, which comes pre-installed with Oxygen's Skeleton package.

1. Login by pointing your browser to http://mysite.com/admin
2. Navigate to Themes and select the Oxygen Theme
3. Scroll down to Theme Options and enable the Search Engine Index toggle

Method 2: Manual Edit

Create user/env/mysite.com/config/themes/oxygen.yaml and its contents. Then rename the folder mysite.com to your production url without www.

Enable indexing by setting this key/value pair:

index: true

Page Options

Prevent a specific page from being indexed

Per-page indexing will only take effect once site-wide indexing is enabled via [#theme-options].

By default new pages may be indexed by search engines. However, you might want to exclude certain content from being indexed, such as error pages or personal data.

Method 1: Admin Panel

1. Login to the the Grav Admin Panel by pointing your browser to http://mysite.com/admin
2. Navigate your desired Page
3. Scroll down to thePage Options fieldset, open it, and set the Search Engine Index toggle to Disabled

Method 2: Manual Edit

Open any Markdown Page in your preferred editor.

Disable indexing of this page by setting this key/value pair:

pageOptions: noIndex: true

Environments

For optimal perfomance in your production environment, create user/env/mysite.com/config/system.yaml and its contents. Then rename the folder mysite.com to your production url without www.

Build Tools

For developers who wish to modify this theme.

Requirements:

• Node.js
• npm
• HTTP Server with this theme's skeleton running

Gulp

A taskrunner to compile JS and SCSS source files so you can adapt this theme to your liking. For example, you might want to configure colors and fonts in src/scss/_config.less.

Installation

Navigate to user/themes/oxygen and install necessary dependencies once with:

npm install

This process may take a while populating node_modules. Please wait patiently.

Usage

npm run serve for development

• opens a livereload browser tab at http://localhost, this path is configurable in gulp.config.json

npm run build for production

• concatenates and minifies assets for deployment

For security purposes, please make sure not to deploy the node_modules folder to any production environment.

Troubleshooting

500 Internal Server Error

If you're getting this error, it means your current installation does not yet have the proper permissions.

The nuclear option is, of course, not recommended for production:

chmod 777 grav-skeleton-oxygen -R

Where grav-skeleton-oxygen is your installation folder.

Examples in the wild

• kittyfishfrommars.github.io - Theme "Oxygen" developed by kittyfishfrommars
• juedisch.info - Jewish activism (german)
• behold.metamotive.co.nz - Original Grav port "Solarize" by hughbris

Please drop me a line if you want yours to be included (hey, it's free publicity).

Credits

• Theme "Oxygen" developed by kittyfishfrommars under the MIT License, for modifications see Changelog
• Based on the Grav port by hughbris under the MIT License
• Developed for Grav CMS under the MIT License
• Header image created by DeepAI under its Generated Content License
• Design inspired by "Solarize" of templated.co under the Creative Commons 3.0 Attribution License
• Font Awesome 4.0.3 by @davegandy - fontawesome.io @fontawesome License - fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
• OpenSans[wdth,wght].woff2: Copyright 2020 The Open Sans Project Authors github.com/googlefonts/opensans (SIL OFL 1.1)