Typhoon Documentation

Learn how to use the full power of Typhoon

Found an issue or a problem that you can't find an answer for? Create an issue in our Premium Issue Tracker.

Header

Before you start

Before you can install a Premium Plugin, you are required to have the License Manager plugin installed. It is a free plugin available in GPM and can be installed like any other through the Plugin section of the admin plugin, or via command line.

$ bin/gpm install license-manager

Installation

First ensure you are running the latest version of Grav 1.6 or Grav 1.7 (-f forces a refresh of the GPM index).

$ bin/gpm selfupgrade -f

The Typhoon theme makes use of some other plugins to work at it's full capacity: color-tools, svg-icons, shortcode-core. These are available via GPM, and because the plugin has dependencies you just need to proceed and install the Typhoon theme, and confirm when prompted to install the others:

$ bin/gpm install typhoon

You can also install the theme via the Themes section in the admin plugin.

Skeleton Packages

Looking for Typhoon skeleton packages to get you started? You can download them directly from GitHub and follow the instructions in the README.md file of each repository.

The quickest way to download the files is to simply click the green Code button then click the Download ZIP.

Download ZIP

Configuration

There are many configuration options for the Typhoon theme. They are broken out into organized sections, but there's also several layers in how they can be overridden. For example, the theme itself has a set of 'default' values that dictate the values site-wide. Then, you can override many of these settings on a per-page level. If this is done on a parent page, that has children, the children will inherit the overrides of the parent, but you can also override them still further in the children. This provides a very flexible architecture, and a simple example of this would be the possibility of configuring a primary color which is unique per top-level page.

Theme Level Configuration

Mode

The mode can either be set to Production or Development. The primary purpose of this option is to control if the theme should use the full site.css file, or the production optimized site.prod.css. It's important to know that while developing the theme and using Tailwind's watch command to automatically compile the various Post CSS files into the single site.css, you should stick to the Development Mode. This generated file is huge (over 4.5MB) as it contains all the utility classes that Tailwind has available. When you approach a point when you are readying your changes to be used in a production environment, you should compile the production css file, and that will result in a much smaller final CSS file (approximately 50k). At this point you can toggle the mode setting to Production.

Default Colors

There are various color configuration options. This section will configure the default colors that are used throughout the site.

  • Text Color → This is the color which is used for the main textual content. It can be any valid tailwind color, e.g. text-primary | text-gray-800 | text-blue-700 etc. You can consult the Available Colors Classes document for more information, or check out the Tailwind Docs.

  • Primary Color → This is the primary accent color used throughout the site. It's commonly used for headers, links, and background colors where contrast is required. This should be a valid HEX color.

  • Lighter Brightness → The primary color has a lighter variant (e.g. text-primary-lighter). How much lighter this actually is depends on this value.

  • Darker Brightness → The primary color has a darker variant (e.g. text-primary-darker). How much darker this actually is depends on this value.

Theme Defaults

Typhoon comes out-of-the box with both light and dark themes.

  • Theme → You can configure Typhoon to use the current System setting (i.e. if your desktop computer is set to a specific option already, or automatically show light or dark theme depending on the time of day), Light or Dark.

  • User Selector → Enables or disables the selector for overriding the theme setting in the footer of the site.

  • Remember Selection → When enabled will use local storage to ensure the preferred user setting for theme is remembered between visits. When disabled, it will only remember for the current session.

Layout Defaults

These two options provide a level of control over the structure of your layout by utilizing Tailwind classes.

  • Wrapper Classes → Wrapper classes control the maximum width of the container, and the padding that should be used. Tailwind is a mobile-first framework, so default values are for smallest viewport, and larger viewports are prefixed by their breakpoint. e.g. md:px-6 px-4 means a default padding of 4 for smaller sizes, and 6 for medium breakpoints and above.

  • Section Classes → Controls the default classes for a section. A section could be a whole page, or a modular page.

Header Bar Defaults

  • Custom Logo → By default the Grav logo used in the header. You can easily upload your own PNG, JPG, or SVG logo to use instead. An SVG is particular useful as it provides the ability to be rendered using the header text color ensuring the logo looks great on either light, dark, or transparent headers.

  • Strip Logo SVG Style → When using a custom SVG, this option can be enabled to strip out any custom <style></style> tags that are embedded in the SVG file to ensure the header text color used.

  • Background → This sets the background to be used. By default, this is either Automatic, Light, Dark, Transparent, or Custom. Light and Dark use a preconfigured dark or light gradient, while Custom, allows you to configure your own background CSS.

  • Custom Background Style → When Background is set to Custom, this CSS style used as the background for the Header bar.

  • Text → The color the text to be used. This is either Automatic, Dark or Light whichever provides the most contrast.

  • Primary Header Levels → By default this is set to 3. That means that the main menu supports 3 levels of navigation. The first is a horizontal menu, and the 2nd and 3rd levels will be dropdown menus. A 4th level will automatically be available as a side menu. If you change this value to 1, you will simply have a row of top-level menu items with no drop down menus. All other levels of navigation will be displayed as a side menu.

    A particular page can choose if it's children should be shown in a side-menu even if they are not at that configured level.

    Hero Defaults

    The Hero is the header section that appears below the logo/menu section at the top of the page. This can be enabled by default for all pages, or disabled by default, then enabled on a page-by-page basis. The defaults just control the look of the overall hero section, the contents of the hero are always controlled per-page.

    • Display → Toggle to control if the hero is always displayed per page. This can be overridden per-page.

    • Hero Alignment → The alignment of the text within the hero section. Options are Left, Center, or Right.

    • Image → While you will most likely set a hero image per-page, you can also set a default image to be used when a specific image is not set. Using a stream is a safe bet, this could be theme://... to reference a location inside the current theme or page://... to reference an image in the user/pages directory structure.

    • Padding Classes → The padding classes used to provide space in the Hero section. The default provides a variety of padding and generally increases the padding as the responsive breakpoints increase. These are tailwind padding classes. More information in the Tailwind Documentation

Hero Overlay

These options are used to control an optional overlay that can cover the image and provide some additional contrast for content that resides in the hero section. There are several options available.

  • Overlay → Choose from the built in values of Dark, Darker, Light, Lighter, Primary, None, and Custom. Where Custom allows you to set a custom color.

  • Custom Overlay Color → When using "Custom" option above, you can specify a custom color here.

  • Overlay Gradient Opacity → The overlay is gradient by default, so provide a start and end opacity (between 0 and 1).

  • Overlay Gradient Direction → Choose from Right, Bottom, Left and Top directions

Footer

The footer appears at the bottom of every page and is by default consists of 3 sections:

  • Menu → A footer menu to link to specific pages that are not considered primary menu items. These could be Terms and Conditions, a Privacy Policy, an FAQ, or perhaps another link to a Contact page. The link itself should be a Grav route if local, (e.g. /contact-us), or a full URL to an external page (e.g. https://somesite.com/terms-and-conditions)

  • Social Links → This is a convenient place to put social media links. Current supported platforms include GitHub, Twitter, Facebook, Instagram, LinkedIn, and Pinterest.

  • Footer Copyright → This is the content that sits at the very bottom of your footer. It can be markdown, use Grav shortcodes, or just be plain HTML.

Page Level Configuration

Typhoon offers override capabilities for most of the default configuration at a page level. When Typhoon renders a Twig template and looks for a certain variable, it checks the current page first, then if that variable is not defined on the current page, checks the page's parent, all the way up to the root of the page structure. If that variable is still not found, the default value from the theme is used.

This allows very powerful configuration options that means you can set specific configurations for a certain section of your site, and then override a specific page in that section if needed. The rest of the site is going to still use the default values.

Hero Options

Hero Content

Each standard page type has a new tab called Hero that lets you configure Hero-specific settings. At the top of this tab is a section called Hero Content, and this is where you control what content shows in your Hero for this page. If no content is provided, the default fallback is to simply show your page's current Title on top of the default image. The overlay will default to the theme's default values.

This section lets you control the following:

  • Subtitle → The text that displays above the main hero title

  • Title Text → The main hero title text

  • Title Color → A specific title color. If not set, will default to white on a dark overlay, and black on a light overlay. You can consult the Available Colors Classes document for more information, or check out the Tailwind Docs.

  • Title 2 Text → A second row of text, works best with a different color. Defaults to same color as main Title.

  • Title 2 Color → Same as Title Color, for the second Title.

  • Default Text → Override the automatically selected color for the Hero section. Values include Auto, Light, and Dark

  • Hero Text → A short hero text paragraph that can be marked-up using Markdown syntax.

    If you want to style an hyperlink you can use TailwindCSS classes. For example: [Typhoon Theme](https://getgrav.org/premium/typhoon?classes=bg-black,bg-opacity-50,hover:text-orange-300,p-1,px-2,rounded,text-orange-500)

  • Buttons → One or more optional buttons are available each with their own settings:

    • Text → The text to display in the button
    • Link → A valid link, either a Grav page route (e.g. /somepath/somepage) or an full URL (e.g. http://somesite.com/somepage)
    • Classes → A string of valid tailwind classes for button color/style

The examples in the screenshot above will result in the following hero:

A more full featured example would be:

Hero Settings & Overlay

You have full control over the Hero Settings, and the Hero Overlay at a page level. You can override any of the default settings here. See the "Theme Level Configuration" for more information on these settings.

Advanced Typhoon Options

Typhoon allows you to set some advanced options at the page level. These are located in the Advanced tab of standard content pages.

Most of these options are exactly the same as the ones available in the theme configuration.

The only important one that is not available in the theme, is the toggle to control where the children will display in the menu.

  • Show Children in Secondary Menu → If you toggle this option, it will force the children of this page that would traditionally show up in the dropdown menu, to display in the sidebar as secondary menu. It really is an override of the Primary Header Levels setting from the theme.

Supported Page Types

Standard Page Types

Typhoon comes standard with some common page types:

  • Default → The standard page with an optional hero section, plus content area
  • Modular → A page that lets you create complex modular pages by building a page from modular sub-child pages. When used, you should setup the Hero as a modular sub-page.
  • Blog → A blog listing page. Children should be Post type pages.
  • Post → A blog post entry page.
  • Error → A simple error page to be used in conjunction with the error plugin.

Modular Page Types

Typhoon also comes with a variety of modular sub page types. These should be used as children of a Modular page. The best way to see these in action is to checkout and install the typhoon-onepage-site skeleton.

  • Starter Module → A starter module that can be used to build other modular page types
  • Hero → Contains the same options as the Page-level Hero section (should be first if used).
  • Features → Provides the ability to create a list of features in either Horizontal or Vertical mode
  • Image Block → A simple block that contains an image and a block of text. You can set a few options such as Subtitle, Title Color, Image and Image Alignment, as well as providing some content.
  • Text Columns → Another simple modular block that uses CSS columns to display your content in a number of columns. The columns are reduced based on responsive breakpoints, but you can set a max number for columns.
  • Gallery → Makes use of the Lightbox Gallery plugin to display a grid of images and have them be clickable and launch a lightbox with a title and description then allow navigation between the other images in the gallery.
  • Contact → A simple contact form. Note: You have to use the Expert mode to make modifications to the actual form.

Theme Modification

Create a Custom Theme from Typhoon

It is strongly advised to create a new theme based on Typhoon if you want to make any modifications to the Twig templates, CSS etc. Typhoon makes a fantastic base theme to build your custom theme on top of because it has already been built responsively, and with a powerful navigation system. These are the most complex and time-consuming aspects of building any theme.

To create your new custom theme, simply install the devtools plugin for Grav. Then from the CLI run the command:

bin/plugin devtools newtheme

This will then ask you for some information about your new theme. When it asks you how to create the new theme select Copy, then choose Typhoon as the theme to copy. Of course this means you must have Typhoon already installed in your Grav installation. This will then create a copy of Typhoon but with your new theme name. From this point forward, make all your changes in the new theme.

Modify the CSS

While Typhoon is highly customizable, you will undoubtedly want to make your own tweaks and modifications to the design of the theme. Some of this is done via CSS which is powered by the TailwindCSS framework. You will need to familiarize yourself with this framework, but have no fear, it's very well documented and has an active and supportive community.

Installing NPM to Compile CSS

99% of everything you need to make modifications is actually already available in Tailwind's utility classes, and you can apply these directly in your Twig templates, or even directly in your content using HTML or shortcodes.

Depending on your platform, installing NPM is different. So please follow the official NPM Installation Instructions to accomplish this. After you have NPM installed you will first need to install the required packages, you can do this by just typing npm install in the root of the typhoon theme:

Replace typhoon with your custom theme name if you have already created a custom theme from Typhoon.

cd user/themes/typhoon
npm install

In case you ever want to upgrade the packages (such as to use the latest version of TailwindCSS) run this:

npm update

Developing Custom CSS

There are times when you need to step beyond the TailwindCSS-provided utility classes and use your own custom CSS. This is most likely to occur when you have no ability to change the output and include the required classes. For these situations, or when you want to make modifications to the core tailwind.config.js file or add your own custom css, you need to recompile the development build/css/site.css file. The best way to do this is to run in a dynamic 'watch' mode that automatically recompiles when a change is detected:

npm run watch

If you want to do a quick compile that does not watch, simply use:

npm run build

The custom modifications should be put in the css/custom/ folder. If you create a new file you should reference that in the top level css/site.css file to ensure it gets picked up and compiled. Best practices for developing custom Tailwind CSS dictates that you should try to use the existing Tailwind classes via the @apply directive as much as possible to ensure global configuration trickles down to your custom CSS.

A good example of this approach can be found in the css/custom/typography.css file, and here's a short extract from it:

body {
  &.debug-screens:before {
    @apply left-inherit right-0;
  }

  @apply text-gray-700;
}

.site-logo {
  img, svg {
    @apply h-full;
  }
}

Building Tailwind for Production

When you are getting ready for a production deployment, you need to make sure you have compiled the Production CSS. This is because the production CSS is purged to only include the CSS classes you are actually using. Also, it is minified to ensure it's as small as possible. You should get into the habbit of running this whenever you do a major change or a push to your production environment. This way you will always have an accurate and optimized production CSS.

To compile the production CSS simply run:

npm run prod

This will create a build/css/site.prod.css file that you can compare to the development build/css/site.css file.

Troubleshooting Production CSS issues

The production version of the Tailwind CSS which is built into buld/css/site.prod.css file utilizes the purgecss package to only include CSS classes that are being used. PostCSS is used to handle this process, and the configuration for where purgecss looks for classes is contained in the tailwind.config.js file. Feel free to modify this file to include other locations if a class is not getting found and included in the production CSS.

By default, Typhoon's purge configuration looks like this:

  purge: [
    '../../config/**/*.yaml',
    '../../pages/**/*.md',
    './blueprints/**/*.yaml',
    './js/**/*.js',
    './templates/**/*.twig',
    './typhoon.yaml',
    './typhoon.php',
    './available-classes.md',
  ],

Feel free to edit or adjust this file to include paths and files that need to be inspected for possible Tailwind CSS classes.

At the root of your Typhoon theme you can find an available-classes.md file that you can consult at any time. This file also allows keeping certain classes upon purge which is used for the build of the production css, even if they have never been used.

Note: If you change the theme name, you should also change the typhoon.yaml and typhoon.php section in the purge configuration.

Modify Twig Templates

Most modifications will take the form of editing the Twig templates which controls the HTML but also is used for setting the Tailwind utility classes for CSS. These are organized in the templates/ folder of the theme.

If you have already created a new custom theme based on Typhoon, then you can edit this as you need. Also, you can override other twig files that come from plugins for example, simply copy the Twig file from the plugin (including any folder structure inside the plugin's templates folder) and copy into your theme's templates folder. Then you can modify the twig as you need to get the desired result.

A good example of this can be seen in the templates/partials/pagination.html.twig where the pagination plugin's existing twig partial, has been copied to Typhoon and modified to make use of Tailwind's CSS utility classes. No custom CSS was required because all the modifications were made directly by modifying the Twig file.

Removing Dark mode

If you only want to remove the "dark" mode from Typhoon theme, it requires a few manual steps. These are best accomplished in a text editor.

edit the tailwind.config.js file in the root of the theme directory and comment out (or remove if you are confident!) the following entries:

darkMode: 'class',

Make sure you save this file. Now you have to remove all the dark: class definitions in the custom CSS. This is a bit of a manual process, so use a good editor like VSCode, PHPStorm, etc.

Do a "find in files" for the css/ folder and search all files for dark:, then one-by-one, remove any of these dark entries. If the CSS entry only has dark entries, then you can remove the whole block. For example, you can remove this whole section:

.notices a {
  @apply dark:text-gray-100;
  &:hover {
    @apply dark:text-white;
  }
}

but this CSS code:

.has-submenu:hover {
    @apply bg-gray-100 dark:bg-gray-800 transition duration-300;
}

Should just be edited to remove the dark: entries only:

.has-submenu:hover {
    @apply bg-gray-100 transition duration-300;
}

When there are no remaining dark: entries left, you should be able to compile the CSS with:

npm run prod

If you get no errors, then you have successfully removed dark mode from the CSS.

You can optionally remove any dark: classes from the templates/ folder as these will no longer have any effect. This is not going to cause any errors, but it will save a few bytes of HTML.