-
Notifications
You must be signed in to change notification settings - Fork 105
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
Comments
Is this to say support for RFC339 dates is planned? If so, looking forward to this. |
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? |
No convincing reason, really. As a practice, I use |
Understandable. |
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.
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.
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
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.
chore: Refactor in preparation for #257
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
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 |
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.
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`.
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.
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`.
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`.
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`.
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.
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`.
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`.
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))
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
Currently, the frontmatter contains
The problem is that we could break custom variables as we add new cobalt variables or customization.
Proposal
Frontmatter may contain:
permalink
to match Jenkins when we break compatibility on the format (from Jekyll's custom format to liquid)/:categories/:year/:month/:day/:slug.html
rather than having the same default as a page to align with Jekylldate
to make the role more clear when we addedmodified_date
ext
extends
to match Jekylldraft
for consistencyis_postPage attributes will be
path
to clarify intent; to be like jekyllsource
to be like jekyllslugexcerpt_separatordate
to make the role more clear when we addedmodified_date
extextendsdraft
for consistencyPath attributes (will be re-examined in #198)
slug
attribute, if available, otherwise file name (missing date prefix, missing extension)title
to match Jekyll when custom attributes are no longer top-leveldowncased/categeory/names
custom
attributes at top level... withpage
attributes at top levelAs 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
permalinkas pathlayoutcategory / categoriesdatepublished (bool)as is_draftAnything else is considered a custom variable and is passed along to liquid without any scoping to protect against breaking compatibility
Page attributes
urlpathtitleidcategoriesdateas published_datecontentexcerptnextpreviousPath attributes
Hugo
Front matter
titledescriptiondatedraft (bool)publishdatemarkup (rst or md)as formatslugurlas permalinkAnything else is considered a custom variable and is passed along to liquid under
.Params
.Page attributes
gutenburg
Front matter
The text was updated successfully, but these errors were encountered: