Hypertext Grav Theme

A fast, simple, compliant Grav CMS theme.


Reference

Date: []

This page describes the technical details and caveats of using the Hypertext theme.

This is a quick tour of the more specialized features you should know about Hypertext, beyond the usual stuff that Grav does.

Page Types

Grav lets you create as many page types as you want, but Hypertext really only knows two types: Pages and Collections. Collections have child pages, while pages do not.

That's it. There's no other difference or benefits to using one type over another in Hypertext.

The default page type is the parent for all page types. Single page types like item inherit directly from the default type and if you are using other types like blog_item, Grav will automatically fall back to the correct default page type so you're totally safe. Page collections like the collection and blog types also inherit from default and they bring additional child management and rendering features that are identical to one another. Use whichever naming you like better.

Key features

Known Issues & Caveats & Notes

Start content headers at ### if you use styles - The default HTML style looks fine whether you start your posts with an H1 header (# H1 Header) or an H3 header (### H3 Header). But, if you want to use one of the many stylesheets built into Hypertext, you should probably start your articles with H2 headers or lower. Hypertext uses H1 for the title of your website, and H2 for the title of the page currently loaded (except the home page), so any headers you use in your article, blog post, or content page should probably start from H3 to avoid weird style problems.

Make your images consistently sized - This is always true of any web work, but it's really important for default-themed HTML. I recommend:

Missing frontmatter is bad - If you do not specify any frontmatter in a markdown file, Hypertext will work almost perfectly. However, you won't get filtering by categories. Hypertext will show you all item children within a blog or collection without filtering them by category.

Not all settings are elegant - I can't test every combination of every little thing. In general, most settings look good in any combination, but there are a few that can get really ugly really fast. For example, using tabular rendering of child pages with every column turned on looks terrible on mobile devices. I trust you to pick the ones you really care about and test across devices to see what works for you.


Theme Settings

To see settings, click "Themes" in the Grav navigation, then on Hypertext.

The theme-level settings include options for structural changes, style changes, and the menu bar. A lot of these global settings can be overridden by child settings (like in your individual pages), so keep an eye out for those.

Structural Options

The structure tab contains settings that influence what structural decisions Hypertext makes in drawing your content. Generally this means semantics, but it can also mean the use of decorative elements (like adding brackets around category names, like this: [category_name]).

Style Options

The style tab contains settings that influence how your content looks or gets rendered. This is the real core of the theme.

CSS/JS

These fields offer settings for whether to allow CSS or JS files. Some plugins include these kinds of files, so this is a great way to suppress them. Remember that these are global settings, which you can override on a per-page basis. For example, you could install the syntax highlighting plugin, disable CSS/JS here, and then enable it only on pages where you know you are showing code.

Themes & Styles

Themes in Hypertext are open-source CSS files available on GitHub and are not my own work. Consider visiting their homepages, contributing, and supporting the authors. Remember that you can test these styles quickly by adding the name or number to a style URL parameter, e.g. YourSite.com/?style=water or YourSite.com/?style=4.

This is a great way to quickly thumb through styles for your website. Use the numbers to find what looks good, then match it to the style in the Theme settings. Try it here on the microsite! Theme 3, Theme 6, Theme 9, Theme 12.

You can check the style examples table in the Appendix to see what each style looks like.

Other Configurations

These fields contain other miscellaneous configuration options that override or replace contents of the built-in style sheets (but do not override your own settings in Custom CSS).

Menu Bar Options

You can add custom menu bar items in this section. Click "Add item" in the lower right corner to get started and from there you can edit details about your links like adding classes or making them open in a new window.

Custom Footer Options

You can add a custom footer to every page on your website from this section.


Page Settings

The page-level settings include overrides to the global settings like whether to show CSS and JS, plus additional content for the page. If your content is actually a directory, you'll find options around ordering and rendering that content.

JS/CSS Overrides

Similar to the global settings, this section lets you override CSS and JS exclusion for rendering this page. For example, if you have the syntax highlighting plugin installed, you might only want to load it on pages where you know you have code, and exclude it elsewhere using this feature.

You can also add custom CSS to just this page in order to add custom style.

Extra Content

Here you can define additional content and metadata for your page, similar to other themes.

What's the difference between a Summary and a Subtitle? A subtitle is usally an extension to the original title. For example, "Raising a puppy" might be the title of my page, and the subtitle might be "How I learned to raise a dog in 2018". On the other hand, a summary is a short introduction or paragraph for the content the user is about to read or click through to. In this same example, the summary would be a 300 character teaser about how cute the puppy was, how excited I was, and how I would learn a lot while training the puppy to be a good boy.

Child Rendering (Collections only)

The render style determines how children of this page will look when rendered in sequence. I included several different types to help give you a few options depending on the kind of content you have. Blogs render best with summaries while factual content looks sharp as a list or a table. Try a few out and see what works best for you.

Examples for Summary, Table, and List views of child pages.

The toggle switches in this section like Show Image and Show Subtitle enable or disable which aspects of a child get rendered. If you turn them all on, things can get cluttered so pick the ones that make sense for your content and go for it.

Not all switches work for all styles. For example, the Table view doesn't allow you to show images, so that switch does nothing for that particular render style.

Children & Ordering (Collections only)

Appendix

Screenshot Name
Theme #0 #0 air
Theme #1 #1 hypertext++
Theme #2 #2 latex
Theme #3 #3 marx
Theme #4 #4 modest
Theme #5 #5 sakura
Theme #6 #6 sakura-dark
Theme #7 #7 sakura-dark-solar
Theme #8 #8 sakura-earth
Theme #9 #9 sakura-vader
Theme #10 #10 stylize
Theme #11 #11 tacit
Theme #12 #12 tufte
Theme #13 #13 w3c-chocolate
Theme #14 #14 w3c-midnight
Theme #15 #15 w3c-modernist
Theme #16 #16 w3c-oldstyle
Theme #17 #17 w3c-steely
Theme #18 #18 w3c-swiss
Theme #19 #19 w3c-traditional
Theme #20 #20 w3c-ultramarine
Theme #21 #21 water-dark
Theme #22 #22 water-light
Theme #23 #23 writ
Theme #24 #24 yorha