Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make frontmatter future compatible #257

Closed
epage opened this issue Jul 4, 2017 · 5 comments
Closed

Make frontmatter future compatible #257

epage opened this issue Jul 4, 2017 · 5 comments
Assignees
Labels
breaking-change enhancement Improve the expected
Milestone

Comments

@epage
Copy link
Member

epage commented Jul 4, 2017

Currently, the frontmatter contains

  • Cobalt customization
    • With path it also then gets turned into an attribute
  • Overriding of cobalt variables
  • custom variables

The problem is that we could break custom variables as we add new cobalt variables or customization.

Proposal

Frontmatter may contain:

  • path
    • will be renamed to permalink to match Jenkins when we break compatibility on the format (from Jekyll's custom format to liquid)
    • why: for determining dest path
    • post default will change to /:categories/:year/:month/:day/:slug.html rather than having the same default as a page to align with Jekyll
  • slug
    • why: to contribute to default dest path
  • title:
    • why: rss
  • description
    • why: rss
  • categories
    • why: to contribute to default dest path, RSS, etc
  • excerpt_separator
    • why: to determine the excerpt
  • excerpt should we still support overriding the auto-created excerpt?
  • published_date
    • renamed from date to make the role more clear when we added modified_date
    • why: rss, sorting
  • format (markdown, raw, etc):
    • reinvented form of ext
    • why: control formatting
  • layout
    • renamed from extends to match Jekyll
  • is_draft
    • renamed from draft for consistency
    • why: filtering posts
  • is_post
    • Removed: Unlikely used; need to actually define semantics if we want to allow customizing this
  • custom
    • why: user defined attributes

Page attributes will be

  • url: absolute path
  • path: path on disk
    • Renamed from source to be like jekyll
  • slug
    • Removed: it was only added for Path attributes
  • title
  • description
  • categories
  • excerpt_separator
    • Removed: it was only meant for the frontmatter to customize cobalt
  • published_date
    • renamed from date to make the role more clear when we added modified_date
  • ext
    • Removed: it was meant for bookkeeping within cobalt
  • extends
    • Removed: it was only meant for the frontmatter to customize cobalt
  • is_draft
    • renamed from draft for consistency
  • is_post
  • custom (eventually)
  • content
  • excerpt
  • next
  • previous

Path attributes (will be re-examined in #198)

  • path: relative path of the file, without output_ext. Normally limited to collections but I think we should make it generally available
  • slug: slugified slug attribute, if available, otherwise file name (missing date prefix, missing extension)
  • filename: raw file name (without extension). Ideally renamed to title to match Jekyll when custom attributes are no longer top-level
  • categories: downcased/categeory/names
  • year
  • month
  • day
  • hour
  • minute
  • second
  • i_day
  • i_month
  • ... with custom attributes at top level
  • ... with page attributes at top level
    • Removed: this was an implementation artifact

As part of this, --dump should add support for showing the page with all defaults filled out for ease-of-debugging.

Prior Art

Jekyll

Front matter

  • permalink as path
  • layout
  • category / categories
  • tags
    • why: feature not implemented yet
  • date
  • published (bool) as is_draft

Anything else is considered a custom variable and is passed along to liquid without any scoping to protect against breaking compatibility

Page attributes

  • url
  • path
  • title
  • id
    • why: we have our own identifier for RSS
  • categories
  • tags
    • why: feature not implemented yet
  • date as published_date
  • content
  • excerpt
  • next
  • previous

Path attributes

Hugo

Front matter

  • title
  • description
  • date
  • taxonomies (like categories and tags?)
  • aliases (for moving pages)
  • draft (bool)
  • publishdate
  • expirydate
  • type
  • CJKLanguage
  • weight (sorting)
  • markup (rst or md) as format
  • slug
  • url as permalink

Anything else is considered a custom variable and is passed along to liquid under .Params.

Page attributes

gutenburg

Front matter

  • title
  • description
  • date: a YYYY-MM-DD or RFC339 formatted date
  • slug: what slug to use in the url
  • url: this overrides the slug and make this page accessible at {config.base_url}/{url}
  • tags: an array of strings
  • category: only one category is allowed
  • draft: whether the post is a draft or not
  • template: if you want to change the template used to render that specific page
  • aliases: which URL to redirect to the new: useful when you changed a page URL and don't want to 404
  • extra (custom)
@epage epage added the enhancement Improve the expected label Jul 4, 2017
@epage epage self-assigned this Jul 4, 2017
@boxofrox
Copy link
Contributor

boxofrox commented Jul 6, 2017

gutenburg

  • date: a YYYY-MM-DD or RFC339 formatted date

Is this to say support for RFC339 dates is planned? If so, looking forward to this.

@epage
Copy link
Member Author

epage commented Jul 6, 2017

That was a comparison with other static site generators to see how my proposal compares.

Is there a reason you'd like RFC339 over the current format?

@boxofrox
Copy link
Contributor

boxofrox commented Jul 6, 2017

Is there a reason you'd like RFC339 over the current format?

No convincing reason, really. As a practice, I use YYYY-MM-DD dates to organize filenames and directories and I'm fond of typing my dates that way. The existing DD MMM YYYY ... format is a bit foreign, but nothing I can't get used to.

@epage
Copy link
Member Author

epage commented Jul 6, 2017

Understandable.

epage added a commit to epage/cobalt.rs that referenced this issue Jul 12, 2017
Previously, we dumped all of the front matter in as page attributes.
Now, native frontmatter attributes are specifically selected.

This is making it possible to move all custom attributes into their own
child Object on the page, which is important for cobalt-org#257.

BREAKING CHANGES

`slug`, `excerpt_separator`, `ext`, and `extends` are no longer page
attributes.  The assumption is that these weren't even really needed.
epage added a commit to epage/cobalt.rs that referenced this issue Jul 12, 2017
Previously, we dumped all of the front matter in as page attributes.
Now, native frontmatter attributes are specifically selected.

This is making it possible to move all custom attributes into their own
child Object on the page, which is important for cobalt-org#257.

BREAKING CHANGES

`slug`, `excerpt_separator`, `ext`, and `extends` are no longer page
attributes.  The assumption is that these weren't even really needed.
epage added a commit to epage/cobalt.rs that referenced this issue Jul 12, 2017
The frontmatter is now a strictly defined format with a `custom` field
for any user-provided values.  Access to this in path formatting or
liquid templates mirrors the documents structure.

Fixes cobalt-org#257

BREAKING CHANGES
- fronmatter
  - excerpt is unsupported
  - is_post is unsupported
  - date is renamed to published_date and the format is validated.
  - extends is renamed to layout
  - draft is renamed to is_draft
  - ext is now exposed as format
- page (liquid)
  - path renamed to url
  - source renamed to path
  - date renamed to published_date
  - draft is renamed to is_draft
  - custom frontmatter attributes parented under `custom`
- path variables
  - filename renamed to name
  - custom frontmatter attributes parented under `custom`
  - permalink default is changed to `/:categories/:year/:month/:day/:slug.html` for posts
@epage epage mentioned this issue Jul 12, 2017
4 tasks
epage added a commit to epage/cobalt.rs that referenced this issue Jul 12, 2017
Previously, we dumped all of the front matter in as page attributes.
Now, native frontmatter attributes are specifically selected.

This is making it possible to move all custom attributes into their own
child Object on the page, which is important for cobalt-org#257.

BREAKING CHANGES

`slug`, `excerpt_separator`, `ext`, and `extends` are no longer page
attributes.  The assumption is that these weren't even really needed.
epage added a commit that referenced this issue Jul 12, 2017
chore: Refactor in preparation for #257
epage added a commit to epage/cobalt.rs that referenced this issue Jul 12, 2017
The frontmatter is now a strictly defined format with a `custom` field
for any user-provided values.  Access to this in path formatting or
liquid templates mirrors the documents structure.

Fixes cobalt-org#257

BREAKING CHANGES
- fronmatter
  - excerpt is unsupported
  - is_post is unsupported
  - date is renamed to published_date and the format is validated.
  - extends is renamed to layout
  - draft is renamed to is_draft
  - ext is now exposed as format
- page (liquid)
  - path renamed to url
  - source renamed to path
  - date renamed to published_date
  - draft is renamed to is_draft
  - custom frontmatter attributes parented under `custom`
- path variables
  - filename renamed to name
  - custom frontmatter attributes parented under `custom`
  - permalink default is changed to `/:categories/:year/:month/:day/:slug.html` for posts
@epage epage mentioned this issue Sep 26, 2017
4 tasks
@epage
Copy link
Member Author

epage commented Oct 21, 2017

Status: the internal representation of the frontmatter has been updated to the new format. We still load using the old format but then convert it to the new format.

See #262

@epage epage added this to the 0.10.0 milestone Nov 9, 2017
epage added a commit to epage/cobalt.rs that referenced this issue Dec 21, 2017
The frontmatter is now a strictly defined format
- Custom data goes in the `data` field to avoid conflicts between user
  data and future cobalt data.
- `date` has been renamed to `published_date` to make it clear what role
  it plays and room for possibly adding a `modified_date`
- Error rather than ignore poorly formed fields
- `path` was a bit ambiguous.  The hope is that `permalink` will be more
  clear.

To help reduce noise when diffing an old site against a new site,
frontmatter fields that are default values are not written out to the
file.

Fixes cobalt-org#257

BREAKING CHANGES

frontmatter
- `date` renamed to `published_date` and will error on bad formatting
- `extends` renamted to `layout`
- `draft` renamed to `is_draft`
- `ext` now exposed as `format`
- `path` renamed to `permalink` and a leading `/` is needed unless a
  path alias is being used.

`cobalt migrate` has support to make these changes for you.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 21, 2017
This is a part of cobalt-org#257

Attributes from a page are now under the `page` object
- `path` -> `page.permalink` to make it clear this is the equivelant of `permalink` in the frontmatter
- `source` -> `page.file.permalink`
  - Under `file` to make room for `page.file.parent`
  - `permalink for consitency with `page.permalink`
- `date` -> `page.published_date`
  - Consistency with the new `published_date` in the front matter
  - Both are renamed to make it clear the role of the date (versus a future `modified_date` that might exist)
- `draft` -> `page.is_draft`
- `previous` -> `page.previous`
- `next` -> `page.next`
- Custom fields have moved from `<field>` to `page.data.<field>`.

BREAKING CHANGE: Liquid `{{ variables }}` have been renamed.

`cobalt migrate` will fix some.  `cobalt build` will most likely fail on
variables missed by `cobalt migrate`.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 21, 2017
The frontmatter is now a strictly defined format
- Custom data goes in the `data` field to avoid conflicts between user
  data and future cobalt data.
- `date` has been renamed to `published_date` to make it clear what role
  it plays and room for possibly adding a `modified_date`
- Error rather than ignore poorly formed fields
- `path` was a bit ambiguous.  The hope is that `permalink` will be more
  clear.

To help reduce noise when diffing an old site against a new site,
frontmatter fields that are default values are not written out to the
file.

Fixes cobalt-org#257

BREAKING CHANGES

frontmatter
- `date` renamed to `published_date` and will error on bad formatting
- `extends` renamted to `layout`
- `draft` renamed to `is_draft`
- `ext` now exposed as `format`
- `path` renamed to `permalink` and a leading `/` is needed unless a
  path alias is being used.

`cobalt migrate` has support to make these changes for you.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 21, 2017
This is a part of cobalt-org#257

Attributes from a page are now under the `page` object
- `path` -> `page.permalink` to make it clear this is the equivelant of `permalink` in the frontmatter
- `source` -> `page.file.permalink`
  - Under `file` to make room for `page.file.parent`
  - `permalink for consitency with `page.permalink`
- `date` -> `page.published_date`
  - Consistency with the new `published_date` in the front matter
  - Both are renamed to make it clear the role of the date (versus a future `modified_date` that might exist)
- `draft` -> `page.is_draft`
- `previous` -> `page.previous`
- `next` -> `page.next`
- Custom fields have moved from `<field>` to `page.data.<field>`.

BREAKING CHANGE: Liquid `{{ variables }}` have been renamed.

`cobalt migrate` will fix some.  `cobalt build` will most likely fail on
variables missed by `cobalt migrate`.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 21, 2017
This is a part of cobalt-org#257

Attributes from a page are now under the `page` object
- `path` -> `page.permalink` to make it clear this is the equivelant of `permalink` in the frontmatter
- `source` -> `page.file.permalink`
  - Under `file` to make room for `page.file.parent`
  - `permalink for consitency with `page.permalink`
- `date` -> `page.published_date`
  - Consistency with the new `published_date` in the front matter
  - Both are renamed to make it clear the role of the date (versus a future `modified_date` that might exist)
- `draft` -> `page.is_draft`
- `previous` -> `page.previous`
- `next` -> `page.next`
- Custom fields have moved from `<field>` to `page.data.<field>`.

BREAKING CHANGE: Liquid `{{ variables }}` have been renamed.

`cobalt migrate` will fix some.  `cobalt build` will most likely fail on
variables missed by `cobalt migrate`.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 30, 2017
This is a part of cobalt-org#257

Attributes from a page are now under the `page` object
- `path` -> `page.permalink` to make it clear this is the equivelant of `permalink` in the frontmatter
- `source` -> `page.file.permalink`
  - Under `file` to make room for `page.file.parent`
  - `permalink for consitency with `page.permalink`
- `date` -> `page.published_date`
  - Consistency with the new `published_date` in the front matter
  - Both are renamed to make it clear the role of the date (versus a future `modified_date` that might exist)
- `draft` -> `page.is_draft`
- `previous` -> `page.previous`
- `next` -> `page.next`
- Custom fields have moved from `<field>` to `page.data.<field>`.

BREAKING CHANGE: Liquid `{{ variables }}` have been renamed.

`cobalt migrate` will fix some.  `cobalt build` will most likely fail on
variables missed by `cobalt migrate`.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 30, 2017
The frontmatter is now a strictly defined format
- Custom data goes in the `data` field to avoid conflicts between user
  data and future cobalt data.
- `date` has been renamed to `published_date` to make it clear what role
  it plays and room for possibly adding a `modified_date`
- Error rather than ignore poorly formed fields
- `path` was a bit ambiguous.  The hope is that `permalink` will be more
  clear.

To help reduce noise when diffing an old site against a new site,
frontmatter fields that are default values are not written out to the
file.

Fixes cobalt-org#257

BREAKING CHANGES

frontmatter
- `date` renamed to `published_date` and will error on bad formatting
- `extends` renamted to `layout`
- `draft` renamed to `is_draft`
- `ext` now exposed as `format`
- `path` renamed to `permalink` and a leading `/` is needed unless a
  path alias is being used.

`cobalt migrate` has support to make these changes for you.
epage added a commit to epage/cobalt.rs that referenced this issue Dec 30, 2017
This is a part of cobalt-org#257

Attributes from a page are now under the `page` object
- `path` -> `page.permalink` to make it clear this is the equivelant of `permalink` in the frontmatter
- `source` -> `page.file.permalink`
  - Under `file` to make room for `page.file.parent`
  - `permalink for consitency with `page.permalink`
- `date` -> `page.published_date`
  - Consistency with the new `published_date` in the front matter
  - Both are renamed to make it clear the role of the date (versus a future `modified_date` that might exist)
- `draft` -> `page.is_draft`
- `previous` -> `page.previous`
- `next` -> `page.next`
- Custom fields have moved from `<field>` to `page.data.<field>`.

BREAKING CHANGE: Liquid `{{ variables }}` have been renamed.

`cobalt migrate` will fix some.  `cobalt build` will most likely fail on
variables missed by `cobalt migrate`.
epage added a commit to epage/cobalt.rs that referenced this issue Jan 4, 2018
This is a part of cobalt-org#257

Attributes from a page are now under the `page` object
- `path` -> `page.permalink` to make it clear this is the equivelant of `permalink` in the frontmatter
- `source` -> `page.file.permalink`
  - Under `file` to make room for `page.file.parent`
  - `permalink for consitency with `page.permalink`
- `date` -> `page.published_date`
  - Consistency with the new `published_date` in the front matter
  - Both are renamed to make it clear the role of the date (versus a future `modified_date` that might exist)
- `draft` -> `page.is_draft`
- `previous` -> `page.previous`
- `next` -> `page.next`
- Custom fields have moved from `<field>` to `page.data.<field>`.

BREAKING CHANGE: Liquid `{{ variables }}` have been renamed.

`cobalt migrate` will fix some.  `cobalt build` will most likely fail on
variables missed by `cobalt migrate`.
@epage epage closed this as completed in 9089c72 Jan 6, 2018
epage added a commit that referenced this issue Jan 9, 2018
This release focused on unleashing a lot of breaking changes that have been
stacking up for a while which also expose a lot of features that have been
inaccessible.  The hope is that from now on, breaking changes will be minor
(like small changes to config) rather than sweeping changes to every file like
this.

Bug Fixes

*   Reducing logging noise ([a7acd2c](a7acd2c))
* **rss:**  Don't error if the RSS folder doesn't exist. ([357cb4b](357cb4b))
* **watch:**  Don't stop on error ([3c4d086](3c4d086), closes [#347](#347))

Features

*   Migrate support for changing _layouts to _includes ([28ae870](28ae870))
* **config:**
  *  Change .cobalt.yml to _cobalt.yml ([c4ee83b](c4ee83b), closes [#348](#348))
  *  Stablize the format ([34e9d54](34e9d54), closes [#199](#199), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/), [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **front:**
  *  Stablize fronmatter format ([9089c72](9089c72), closes [#257](#257), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Change date to YYYY-MM-DD ([1e19ae0](1e19ae0), closes [#349](#349), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Change permalink variable names ([e78b806](e78b806), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Change permalink to well-defined format ([c6c4d7a](c6c4d7a), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Standardize permalink behavior ([6730eb6](6730eb6), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **excerpt:**  Better define non-existent behavior ([129c574](129c574))
* **page:**
  *  Upgrade liquid ([2ec3f24](2ec3f24))
  *  Generalize is_post / posts ([d280a35](d280a35), closes [#323](#323), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Make page variables future-proof ([6f62dea](6f62dea), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  page.file.parent variable ([dce1d59](dce1d59), closes [#338](#338))
* **serve:**
  *  Adjust base_url for localhost ([e75e139](e75e139), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Merge `serve` and `watch` ([d2f22d5](d2f22d5), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **debug:**
  *  Report asset files ([5d77b7f](5d77b7f))
  *  Generalize debug commands ([087d991](087d991), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))

Breaking Changes

`cobalt migrate` was created to help mitigate the cost of most of these breaking changes.

* **config:**  Stablize the format ([34e9d54](34e9d54), closes [#199](#199), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/), [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **debug:**  Generalize debug commands ([087d991](087d991), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **front:**
  *  Change date to YYYY-MM-DD ([1e19ae0](1e19ae0), closes [#349](#349), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Change permalink variable names ([e78b806](e78b806), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Change permalink to well-defined format ([c6c4d7a](c6c4d7a), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Standardize permalink behavior ([6730eb6](6730eb6), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Stablize fronmatter format ([9089c72](9089c72), closes [#257](#257), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **page:**
  *  Liquid errors on undefined variables ([2ec3f24](2ec3f24))
    * This was done to help catch migration problems and to move us in the direction of easier debugging of problems
    * The restriction might be loosened in some cases (like `{% if var %}`).
  *  Generalize is_post / posts ([d280a35](d280a35), closes [#323](#323), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Make page variables future-proof ([6f62dea](6f62dea), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
* **serve:**
  *  Adjust base_url for localhost ([e75e139](e75e139), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))
  *  Merge `serve` and `watch` ([d2f22d5](d2f22d5), breaks [#](https://github.com/cobalt-org/cobalt.rs/issues/))

Performance

* **serve:**  Reduce duplicate rebuilds ([8f2679c](8f2679c))
epage added a commit to epage/cobalt.rs that referenced this issue Mar 19, 2018
This was removed in cobalt-org#257 because it was deemed as not being needed but a
use case was found in cobalt-org#384.  I'm not fully convinced about that use case
but I feel there are probably others, like in having an identifier to
use in creating a table of contents.

Fixed cobalt-org#384
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
breaking-change enhancement Improve the expected
Projects
None yet
Development

No branches or pull requests

2 participants