gizmecano / grav-theme-hereditor Goto Github PK

View Code? Open in Web Editor NEW

1.0 2.0 0.0 3.01 MB

Hereditor Grav theme

Home Page: https://htg.gizmecano.net/

License: MIT License

CSS 48.38% JavaScript 5.00% PHP 0.28% Twig 46.34%

grav-theme blog grav-cms responsive-design responsive-theme responsive-web-design-project theme-development

grav-theme-hereditor's Introduction

Hereditor Theme

About

Background

The Hereditor theme for Grav is a detached fork of the Mediator theme developed by Grav Team and contributors, which was a port of the Mediator theme for Jekyll designed by Dirk Fabisch, which in turn was inspired by the Readium theme for Ghost elaborated by Sven Read.

The wording Hereditor comes from a Latin verb relating to heirs what seems quite logical for a project that has so many ancestors!

Theme preview

In order to preview this theme in action more effectively than a simple screenshot, a demonstration implementation (based on the Hereditor skeleton) is available online.

Downloads

You can download the Hereditor theme individually on its own repository but it might be better to download the full Hereditor skeleton.

References

You can find out more info about customizing a Grav theme (as well as basic usage documentation on the official Grav Documentation) and check the full source code on GitHub.

License

The Hereditor theme is free and open source software, distributed under the MIT License version 2 or later. So feel free to to modify this theme to suit your needs.

Overview

Features

Minimal design
Responsive layout
Header images in posted articles
Support of featured posted articles
Implementation of Font Awesome for icons fonts use
Integration of free and open source improved fonts (WOFF 2.0)

Supported page types

The Hereditor theme was mainly conceived to craft a simple blog and supports four distinct page types via templates:

default: a template used to display the default blog listing view
error: a very simple template to display an error page
post: a full page for displaying a blog post
page: similar to the post template, but without any author information

Embedded assets

Font Awesome (version 4.7.0, font file licensed under the SIL OFL 1.1 and CSS file licensed under the MIT License), is a suite of (...) pictographic icons for easy scalable vector graphics on websites, created and maintained by Dave Gandy
Inter (version 3.19, © The Inter Project Authors, licensed under the SIL Open Font License 1.1), is a variable font with several OpenType features which has been crafted & designed for computer screens ("Inter" is trademark of Rasmus Andersson)
Libertinus Fonts (version 7.040, © The Libertinus Project Authors, released under the terms of the Open Font License, version 1.1, with Reserved Font Name "Linux Libertine", "Biolinum", "STIX Fonts"), is a typeface project which includes four main type families which were originally forked from Linux Libertine (only four files for two weights --Regular and Bold-- in two styles --Regular, Italic-- of the Serif family are embedded in the theme)
normalize.css (version 8.0.1, © Nicolas Gallagher and Jonathan Neal released under MIT License) is a small CSS file which aims to render (...) elements more consistently (...) with modern standards (and) precisely targets only the styles that need normalizing

Additional pictures

Additional pictures used to craft the Hereditor skeleton package belong to their original authors according to the Unsplash licence. The list below provides precise attributions:

Using the skeleton

The simplest way to install the Hereditor theme is to download and install the Hereditor skeleton package:

Download the Hereditor skeleton
Unzip the package into your web root folder.
Point your browser at the folder.

Check out the general Grav installation instructions for more details on this process.

It is possible to install just the theme as described below, but page content will need to fit the templates supported the Hereditor theme. It is strongly advised to at least install the Hereditor skeleton package as described above to see the structuration of the theme in action.

Installing the theme

Installing the Hereditor theme can be done in one of two ways. Using the GPM (Grav Package Manager) installation method enables to quickly and easily install the theme with a simple terminal command, while the manual method enables to do so via a zip file.

GPM installation

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

bin/gpm install hereditor

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

Manual installation

To install the theme, just download the zip version of this repository and unzip it under /your/site/grav/user/themes. Then, rename the folder to hereditor. These files can be found on GitHub or via GetGrav.org.

All the Hereditor theme files should be into the folder /your/site/grav/user/themes/hereditor.

Updating the theme

As development for the Hereditor 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 the Hereditor theme is easy, and can be done through Grav's GPM system, as well as manually.

GPM update

The simplest way to update this theme is via the Grav Package Manager (GPM). Navigate to the root directory of the Grav install using the system's Terminal (also called command line) and type the following:

bin/gpm update hereditor

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

Manual update

Manually updating the Hereditor theme is pretty simple:

Delete the your/site/user/themes/hereditor directory
Download the new version of the Hereditor theme from GitHub or GetGrav.org
Unzip the zip file in your/site/user/themes and rename the resulting folder to hereditor
Clear the Grav cache using admin panel or following command:

bin/grav clear-cache

Note that any changes made to any of the 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.

Setup

Theme activation

To set the Hereditor theme as the default theme, the steps to follow are:

Navigate to /your/site/grav/user/config
Open the system.yaml file
Change the theme: setting to theme: hereditor
Save the changes
Clear the Grav cache using admin panel or following command:

bin/grav clear-cache

Once this is done, the new theme should be available 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 hereditor folder.

Site parameters

In case the Hereditor theme is activated on a fresh Grav install, some parameters in the user/config/site.yaml file have to be populated:

title: name of your site
description: description of your site
author.name: name site owner
author.email: mail address of the site owner
author.bio: short one sentence biography

The file should look a bit like this:

title: Website name
description: A short description for the purpose of the website
author:
  name: Author Name
  email: [email protected]
  bio: A short description of the author of the website

Custom styles for plugins

The Hereditor theme includes custom styles for specific plugins (Markdown Notices, Pagination). To be properly loaded, the Use built in CSS option has to be set to false (using the admin panel or configuring the YAML file in the users/config/plugins/ folder):

built_in_css: false

Configuring images and links

Website images

Basically, the Hereditor theme is arranged to use two images for the entire website:

logo: used into default page and to link toward the home page (but also as basic shortcut icon). This image aims to represent the website and should not exceed a size close to 300px × 300px.
author.image: set as illustration in the mini-bio. This image aims to represent the author of an article and should not exceed a size close to 300px × 300px.

These two images have to be defined in your /your/site/grav/user/config/site.yaml file, such as:

logo: /user/images/logo.png
author:
  image: /user/images/avatar.png

Article header images

Header images can be used in articles which are based on the post template. Any header image has to be declared in the front-matter section of the post, by adding a tag image populated with a proper URL to the intented file, such as this code sample (if the image is set in the same folder as the article):

image: header-image.jpg

Social links

In order to set social profiles features to be embedded in the Hereditor theme configuration, add the following to your /your/site/grav/user/config/site.yaml file:

social.icon: name of the social platform
social.link: the main URL of the plateform
social.user: the specific user name on the plateform

Below is an example for a Twitter account:

social:
  - icon: twitter
    link: https://twitter.com/
    user: username

grav-theme-hereditor's People

Contributors

Stargazers

Watchers

grav-theme-hereditor's Issues

Fix various elements in head section

Fix various data in <head> section set in \templates\partials\base.html.twig files, such as:

<title>: append main site name in <title> element introduced by —
<link rel="canonical">: use true canonical variable
remove outdated comments:
1. Using the viewport meta tag to control layout on mobile browsers
2. Specifying legacy document modes)
remove (pro tempore) meta values for:
1. HandheldFriendly
2. MobileOptimized
3. apple-mobile-web-app-capable
4. apple-mobile-web-app-status-bar-style

Reconsider various existing styles

Reconsider various existing styles in /css/main.css

.logo-readium
.post .article-image .author-name
.post .bottom-teaser .isLeft a
.post .bottom-teaser .isLeft p.bio
.post .bottom-teaser .isLeft p
.post .bottom-teaser .isRight .site-footer .poweredby
.post .bottom-teaser .isRight .site-footer a
.post .post-content p + p
.post .post-content p

Embed fonts previously delivered remotely

In order to replace fonts previously delivered remotely (from Brick), configure CSS and WOFF files to be directly embedded in the core of the theme:

Linux+Libertine: substituted by Libertinus in b3b9bff
Open+Sans: substituted by Inter in e5e8250

Prepare preprocessor scripts removing

As most recent CSS specifications (especially variables) seem largely efficient for doing this kind of job, preprocessor script language stuff may be considered as useless.

templates\partials\base.html.twig

Overhaul development environment

Overhaul various development environment files (non-versioned workspace included):

.vscode/extensions.json
.vscode/settings.json
.editorconfig

Check and adjust hypothetical styles

Various styles are present in the original theme but have not been implemented on the current working skeleton. Check which ones could be properly reintroduced and adjusted to fit expected needs.

.post .post-content blockquote + .post .post-content blockquote p (2ec1e5a + 8d226e5)
.post .post-content figcaption + .post .post-content figure + .post .post-content figure img (f229217)
.post .post-content hr (c2da088)
.post .post-content li + .post .post-content ol + .post .post-content ul (6e0ce4a)
code + pre (8708da7)

Redesign main stylesheet

Create a specific hereditor-outline.css for redesigning main stylesheet. Indeed, due to the breaking changes between the initial structure using SCSS files to the benefit of raw CSS styles, significant adjustments have to be considered.

Check existing styles in use in templates:
- default.html.twig: ffd0ec9
- post.html.twig: a679e2d
Collate font stacks using CSS variables: a5de088

Remodel content in footers

Remodel content initially set in various footers:

\templates\post.html.twig
\templates\partials\base.html.twig

Revise project blurb

Revise sections:

Installation
Updating
Setup

Add section

Configuration

Revise versioning settings

Revise various files related to versioning settings:

.gitattributes

Improve various custom `CSS` rules

Improve and/or harmonize various custom CSS rules, such as:

Renovate various tags

Due to numerous divergences since the initial project was forked, various tags have to be checked and their possible entries in the changelog have to be revised accordingly.

Fix date for tag 1.3.1-alpha (8cf5c6a)
Remove tag 1.4.0 (4733174)

Reshape project management

Define, revise and/or readjust various settings files, such as:

/
- .editorconfig
- .gitattributes
- .gitignore

Complete miscellaneous element into the repository, such as:

Labels
- addition #29BAA5 : New files which don't exist in upstream repository
- commit #EC565C : Committed changes in upstream repository
- request #ba87cf : Proposed changes in upstream repository
- setting #66595C : Project environment and workflow
- split #8E44AC : Split files which exist in upstream repository
- support #1E5397 : Help files and various documentation
- upstream #190629 : Tasks related to tracking upstream repository

Monitor rendering of `twig` templates

Over the checks and development steps of the skeleton, some twig templates seem to include potential issues and/or have some concerns that deserve to be adjusted on a case-by-case basis.

partials/base.html.twig: Remove obsolete stylesheet for palette (ad4513a) and temporary stylesheet (f135bad)
partials/article.html.twig: Revise excerpt size (09ec62e)
partials/postmeta.html.twig: Revise tags display on posts (ffa8625)
post.html.twig: Remove hard coded sharing section in article footer (59ecd4d)

Revamp various items set in the post partial template

Revamp items set in templates\partials\postmeta.html.twig file:

.post-meta-text

Improve development settings

During the development process, some of the tools used may be significantly optimized and some settings in settings.json may need to be improved accordingly.

Add settings for built-in CSS formatter according to Built-in CSS/LESS/SCSS formatters (d9027af + cd6b55c)
Add markdownlint configuration in settings.json (3744688)

Fix minor issues in initial main stylesheet

Fix various minor issues in initial main stylesheet /css/main.css:

.post .post-content blockquote p
.post .article-image .author-image
.post .noarticleimage .author-image

Check scripts usage

Check scripts usage in order, depending on the case, to update them or remove them (when a script is considered useless).

jquery.fitvids.js: 5679529
readingTime.min.js: a3bff85

Add new variables used for translation

Add new variables used for translation in languages.yaml:

Check compatibility with versions 1.7.0 to 1.7.18

Check compatibility with new versions which have been released from 19-01-2021 to 19-07-2021 and fix potential issues with related theme elements.

Adjust documentation during building process

The current content of the documentation file (last committed in 2499a81) is not suitable for the current build process and should be adjusted accordingly.

Renovate section about background history (b88e19b)
Subtract mentions about Grav Package Manager (4cdc4b5)

Check operating of several native files

Check operating of native or modified files set in upstream repository:

Missing metadata.html.twig (cf. issue getgrav/grav-theme-mediator#21)
Test some recent modifications made in upstream directory (cf. commit 7c08fbb)

/js
- /index.js
templates/partials
- /base.html.twig
- /javascripts.html.twig

Check compatibility with 1.6 series versions

Check compatibility with 1.6 series versions, i.e.:

Check and adjust temporary styles

Various styles are present in the original theme and have to be revamped or improved during future developments on the current working skeleton. Check which ones could be properly adjusted to fit expected needs.

.container .featured(96d0476)
.post .article-image .post-meta-text + .post .article-image .fa-angle-down (6a56aff)
.post .bottom-teaser a (9314ca8)

Move deferred javascript assets

With the changes made in the version 1.4.0 (related to deffered assets), some specific features related to .post-image-image and .teaserimage-image classes don't work properly.

Moving the bottom block from base.html.twig into javascripts.html.twig template seems to reorder rightly assets in order to run script which needed by these classes.

templates/partials
- base.html.twig
- javascripts.html.twig

Prepare explicit split from upstream repository

Replace all occurrences of the upstream repository name in:

/
- blueprint.yaml
- hereditor.php
- hereditor.yaml
- README.md

Prepare theme language translations

Replace any terms or expressions that are directly hard coded in the template files with theme-specific variables.

languages.yaml
templates/default.html.twig
templates/error.html.twig
templates/partials/base.html.twig
templates/partials/pagination.html.twig
templates/partials/postmeta.html.twig
templates/post.html.twig

Break from upstream

Due to the many changes made since the original cloning of the Mediator Grav Theme project, it now seems time to detach the fork from the initial upstream repository: no more commits have been directly merged since March 2019 in 3b9f9b1.

Revise assets embedding

Revise assets embedding by properly integrating required and used files (including binaries), but also appropriate licenses.

Font Awesome (3444b82)
Inter (e4c4705 + 8c5e6a2)
Libertinus Fonts (ab1e632)
normalize.css (df87bdb)

Embed assets previously delivered remotely

In order to replace assets previously delivered remotely (from cdnjs), configure various files to be directly embedded in the core of the theme:

font-awesome.css: 0b2999b, 9b18b3e and 1f24c94
normalize.min.css: dbfd981

Rearrange color palette

Create a specific hereditor-palette.css and rearrange color palette by following various steps:

Collate initial hexadecimal colors using CSS variables: 1816f40
Collate initial named colors using CSS variables: b2558e2
Collate initial RGB colors using CSS variables: a53b795
Convert hexadecimal values to RGB values: 891c16a

Append `raw` filter on `content` statement

As done in getgrav/grav-theme-mediator@90abfe6, a raw filter have to be appended on content statement in various files, in order to be ready for the 1.7 version (according to documentation).

error.html.twig
partials/base.html.twig
post.html.twig

Check compatibility with version 1.7.19 to 1.7.22

Check compatibility with new versions which have been released from from 31-08-2021 to 16-09-2021 and fix potential issues with related theme elements.

1.7.19
1.7.20
1.7.21
1.7.22

Review migration guide

In order to successfully update all possible requisite elements for the 1.7 series versions, checking and evaluating various steps mentioned in the official upgrade guide seems to be required.

Check usage of remaining styles

Create a temporary hereditor-interim.css file for storing various style definitions which are not currently fully improved nor implemented, according to classification below:

Temporary styles, which are present in the original theme and have to be revamped or improved during future developments
Hypothetical styles, which are present in the original theme but have not yet been implemented in working skeleton and could be properly reintroduced during future developments
Deprecated styles, which were present in the original theme but are no longer used by any of the templates
Unused styles, which were present in the original theme but seem not to be used by any of the templates

Check possible additions of custom styles for plugins

Some plugins may add elements to templates and rulesets to styles: their features have to be checked in order to harmonize their potentials additions to the whole theme implementation.

Login: Disabling the Use built in CSS option allows not to load an additional stylesheet
Markdown Notices: Disabling the Use built in CSS option allows to add customized styles for this plugin
Pagination: Disabling the Use built in CSS option allows to add customized styles for this plugin

Create clean basis branch

Before considering any split from original upstream, try to set a clean basis branch is prerequite.

This branch should include main commits (integrated in official releases) but also various requests (considered as constructive or useful).

The cherry-picking method have to be preferred in order to sort correctly these changes.

172ce1e (cherry picked from commit ab08fe3)
f2193b0 (cherry picked from commit f787646)
c1c8910 (cherry picked from commit 01c7af0)
afc4174 (cherry picked from commit ad64a97)
f7fd4cd (cherry picked from commit c3bfb27) (proposed in getgrav/grav-theme-mediator#6)
b2812e0 (cherry picked from commit ea75b8c) (considered in #3 and proposed in getgrav/grav-theme-mediator#20)

Check and adjust (potentially) deprecated styles

Several styles were initially present in the original theme but seem to no longer be currently used by any of the activated templates. They have to be properly checked and potentially adjusted to fit running needs.

.bottom-closer .inner (83c4ba6)
.post .noarticleimage (4af09ba)

Check embedded components relevance

Check embedded components relevance in templates\partials\base.html.twig:

Font-Awesome: use version 4.7.0 via cdnjs.com
normalize.css: use version 8.0.1 via cdnjs.com

Prepare native meta properties support

According to official Grav documentation (cf. Meta Page Headers in §2 and Blogging Metadata in §15), the values which are stored in /user/config/site.yaml as well as in each frontmatter posts (or each frontmatter.yaml files) can be natively used to implement the meta properties list appointed in the main <head> section (and therefore, a workable way to avoid any plugin requirement to specifically manage this kind of values).

Prepare native support of various meta properties in /templates/partials/base.html.twig:

OpenGraph
Schema.org
Twitter (according to Cards Markup Tag Reference)

Fix metadata description content in homepage

Into homepage, <meta name="description" /> is displayed without any content, while it is supposed to be rended as <meta name="description" content="{{ site.description }}">.

Compile various previously used fixes and modifications

Compile various previously used fixes and modificationsn such as:

Fix hard coded links for RSS feed (previously opened as an issue in the upstream repository on getgrav/grav-theme-mediator#19)
Change hard coded link for shortcut icon (in order to use logo.png set in /user/images/ folder)

/template
- /partials/base.html.twig
- /post.html.twig

Amend main license

According to this answer, adding a copyright notice in a MIT licence is allowed after forking a project.

Consequently, the licence file can be amended by:

include previous works made by the original team from the initial commit (b9452af) until the last one (afc4174) which has been integrated into this fork
append modifications made specifically since its first explicit splitting commit (b73c9ff) which wasn't merged in the upstream project

Check and adjust (potentially) unused styles

Several styles were initially present in the original theme but seem not to be used by any of the templates. They have to be properly checked, renovated if eventually needed or removed if obsolete or unnecessary.

#disqus_thread
.archive-template
.post-tag-articleimage
.post-template .content

Adjust various current styles

Adjust various current styles set in \css\main.css

Balance colors shades

The colors initially used in the original theme were collated during previous tasks (1816f40, b2558e2, a53b795 and 891c16a)

Currently, the converted palette contains 13 distinct color shades (named according to standard colors that can be considered as closest).

The effective use of each of these colors have to be checked
Those of them whose tones are close (and whose use seem redundant and/or unecessary) would benefit to be merged
Associated variables could probably be named according to main usage within the theme and not based on a generic color name.

Rebuild error template

Rebuild templates\error.html.twig:

Rebuild main content
Paste generic footer block

Revise social links integrations

Revise social links integrations set in /templates folder:

default.html.twig
post.html.twig : replace sharing window with simple web intent

Renovate styles for anchor links

Styles for anchor links from the initial theme seem very oversimple and would benefit would benefit from being extensively renovated, especially by including useful pseudo-classes (such as :active, :focus, :visited, etc.).

Update initial documentation

Update various items in the initial documentation files. Most important elements are listed below: