Kotsu
Kotsu copied to clipboard
LotusTM
Empower Gray Matter structure
I'd like to improve Gray Matter structure and give it some more power to redefine some backed-in properties of base layout.
As a side effect, it will resolve #59 and #175.
Right now usually we deal with following Gray Matter. I've took Blog page Matter as an example, since it usually feature more properties than usually other pages do, so it will give better understanding:
---
title: Example article
breadcrumbTitle: Example article
contentTitle: Example article
navTitle: Example article
metaDesc: Example article generated with %(company)s
shortDesc: Example article generated with %(company)s. Wanna more?
author: LotusTM
date: 2015-10-12T14:48:00
class: 'p-blog'
applyWrapper: true
showContentTitle: true
showBreadcrumb: true
showSidebar: false
Though, for most pages it is enough to have those mandatory properties:
---
title: Example article
breadcrumbTitle: Example article
contentTitle: Example article
navTitle: Example article
metaDesc: Example article generated with %(company)s
I'm thinking to change structure as follows. Note that it will now include all possible for Gray Matter properties, so you could take picture of fully configured page, which uses a lot of overrides:
---
title:
header: # <title>header title</title>, `title` before
breadcrumb: # `breadcrumbTitle` before
content: # `contentTitle` before
nav: # `navTitle` before
meta:
description: # named `metaDesc` before
themeColor: # defined Android browser bar color
viewport: # defines how page zoom behaves on mobile devices
og: # Facebook OG
type:
site_name:
locale:
url:
title:
description:
image:
twitter:
card:
site:
creator:
url:
title:
description:
image:
image:alt:
link:
alternate: # <link rel='alternate' hreflang='en-US' href='https://example.com/en-US/mypage'>
- hreflang:
href:
...
canonical: # <link rel='canonical' href='http://example.com/other-page/'>
- {type your href here}
...
excerpt: # named `shortDesc` before
author:
date:
class:
applyWrapper:
showContentTitle:
showBreadcrumb:
showSidebar:
As you can see, it finally allows to redefine Facebook OG and Twitter values for each page, whenever you need it, provide custom viewport and theme color, and even add additional alternate urls (Kotsu already generates them for you, but you might need to specify your own), or specify canonical urls list.
Though, I hesitate about new structure and wonder are some introduced renames good enough,
Regarding structure, I also have alternative version, where meta and link properties are flattened to root level. This makes dot notation calls shorter (typing page.meta.og.site_name can be quite annoying), but I'm not sure doesn't it introduce any issues.
For instance, description property falls into root and it might be unclear that it's one of meta descriptions. I can imagine someone might want to put into description desc of his page, not realizing that it's actually a meta description which should be not longer than 140 chars.
From another perspective, properties like theme-color or viewport placed under meta slightly bothers me too, since while technically they are <meta>, on practice for some people it might be not obvious that those properties should be placed under meta, since usually we assume under meta some metaphoric description, tiles, etc, but not those technical values. Yeap, despite it's false assumption.
I also slightly dislike that everything in root, but title has nesting.
Anyway, here it is:
---
title:
header: # <title>header title</title>, `title` before
breadcrumb: # `breadcrumbTitle` before
content: # `contentTitle` before
nav: # `navTitle` before
description: # named `metaDesc` before
themeColor: # defined Android browser bar color
viewport: # defines how page zoom behaves on mobile devices
og: # Facebook OG
type:
site_name:
locale:
url:
title:
description:
image:
twitter:
card:
site:
creator:
url:
title:
description:
image:
image:alt:
alternate: # <link rel='alternate' hreflang='en-US' href='https://example.com/en-US/mypage'>
- hreflang:
href:
...
canonical: # <link rel='canonical' href='http://example.com/other-page/'>
- {type your href here}
...
excerpt: # named `shortDesc` before
author:
date:
class:
applyWrapper:
showContentTitle:
showBreadcrumb:
showSidebar:
To show some real examples, here are properties which most likely be used on Blog pages. Overriding of other properties is very rare case.
Was:
---
title: Example article
breadcrumbTitle: Example article
contentTitle: Example article
navTitle: Example article
metaDesc: Example article generated with %(company)s
shortDesc: Example article generated with %(company)s. Wanna more?
author: LotusTM
date: 2015-10-12T14:48:00
class: 'p-blog'
applyWrapper: true
showContentTitle: true
showBreadcrumb: true
showSidebar: false
Became:
---
title:
header: Example article generated with %(company)s
breadcrumb: Example article generated with %(company)s
content: Example article generated with %(company)s
nav: Example article generated with %(company)s
meta:
description: Example article generated with %(company)s
themeColor: 'red'
og:
type: 'article'
image: /pathto/img.png
twitter:
image: /pathto/img.png
link: # to be hones, this is rare case, but can happen
canonical:
- /myotherpage/
- /anotherpage/
excerpt: Example article generated with %(company)s. Wanna more?
author: LotusTM
date: 2015-10-12T14
class: 'p-blog'
Or with flatten structure:
---
title:
header: Example article generated with %(company)s
breadcrumb: Example article generated with %(company)s
content: Example article generated with %(company)s
nav: Example article generated with %(company)s
description: Example article generated with %(company)s
themeColor: 'red'
og:
type: 'article'
image: /pathto/img.png
twitter:
image: /pathto/img.png
canonical:
- /myotherpage/
- /anotherpage/
excerpt: Example article generated with %(company)s. Wanna more?
author: LotusTM
date: 2015-10-12T14
class: 'p-blog'
But on most common pages we will see
---
title:
header: Example article generated with %(company)s
breadcrumb: Example article generated with %(company)s
content: Example article generated with %(company)s
nav: Example article generated with %(company)s
meta:
description: Example article generated with %(company)s
class: 'p-somepage'
Note how stupid meta.description looks here... lonely property.
It would be not that lonely if we move title.header to meta.title, but it breaks our pattern of specifying all titles in one place:
---
title:
breadcrumb: Example article generated with %(company)s
content: Example article generated with %(company)s
nav: Example article generated with %(company)s
meta:
title: Example article generated with %(company)s
description: Example article generated with %(company)s
class: 'p-somepage'
Or whole thing flatten
---
title:
header: Example article generated with %(company)s
breadcrumb: Example article generated with %(company)s
content: Example article generated with %(company)s
nav: Example article generated with %(company)s
description: Example article generated with %(company)s
class: 'p-somepage'
Note that we might periodically have on pages some technical or UI related properties, like:
class: 'p-blog'
applyWrapper: true
showContentTitle: true
showBreadcrumb: true
showSidebar: false
Those control UI displaying. The usually appear on Index page, or any other page, which might have unique layout, but shares most parts of base layout. For instance, some landing pages.
Or we might have some other technical properties, like
generatorsBrands:
- SomeCompany
generatorsTags:
- cool-stuff
or
generatorId: 55443
But I do not see anything better than placing them directly in root of Gray Matter, unless there are some good proposals.
