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

Set patterns for page files to declare metadata #2

Closed
KyleAMathews opened this issue Jun 13, 2015 · 4 comments
Closed

Set patterns for page files to declare metadata #2

KyleAMathews opened this issue Jun 13, 2015 · 4 comments
Labels
help wanted Issue with a clear description that the community can help with.

Comments

@KyleAMathews
Copy link
Contributor

Markdown has standardized on frontmatter. Don't want to force frontmatter on other file types e.g. JSX.

My proposal for the post-build is that we create a special metadata gathering webpack entry file that pulls in all pages and grabs their metadata. Each loader would need to return a metadata key.

@KyleAMathews KyleAMathews changed the title Have universal way for page files to declare metadata Set patterns for page files to declare metadata Jun 22, 2015
KyleAMathews added a commit that referenced this issue Jul 22, 2015
@KyleAMathews
Copy link
Contributor Author

With React files, using convention currently of looking for a static function named metadata that returns an object. Seems to work well. Thoughts?

@KyleAMathews KyleAMathews added the help wanted Issue with a clear description that the community can help with. label Aug 3, 2015
@fson
Copy link
Contributor

fson commented Jan 20, 2016

I needed something like this for HTML files. As an easy to implement solution I've added frontmatter for HTML files: #116

@KyleAMathews
Copy link
Contributor Author

To make this actionable/finishable – let's let say React components can set a static function called gatsbyData (so doesn't clash with any thing else) which returns a plain JS object and this and HTML/md/yaml/json/etc. loaders should all put their data on page.data.

I'll leave this issue open until this is documented and tested.

@KyleAMathews
Copy link
Contributor Author

KyleAMathews added a commit that referenced this issue Mar 28, 2017
* Add missing dependency configstore

* Add note about needing to set path to cloned repo

* Fix gatsby-dev logic
gosseti pushed a commit to gosseti/gatsby that referenced this issue Jun 5, 2017
KyleAMathews added a commit that referenced this issue Apr 22, 2018
[v2] Implement RFC #2 removing special layout component
calcsam pushed a commit that referenced this issue Oct 16, 2018
This is the first step towards gatsby themes. It is low level and defines the way multiple gatsby sites compose by defining the way in which gatsby-config's compose. Everything else will build on top of this composition model so it's important to make it extensible and maintainable for the future.

For those that are mathematically inclined, this defines a monoid for the gatsby-config data structure such that `(siteA <> siteB) <> siteC === siteA <> (siteB <> siteC)`. This makes it nice when thinking about sub-theming in the future (imagine a complex `ThemeA <> subthemeA <> ThemeB <> subthemeB <> user-site` situation)

This method of composition opens the door to themes and sub-themes and allows us to get more user input into how to deal with potentially conflicting artifacts (such as two singleton plugins being defined), test out approaches to generic overriding the rendering of components in user-land, and more.

## Themes

A theme is defined as a parameterizable gatsby site. This means that gatsby-config can be a function that accepts configuration from the end user or a subtheme. This is important because in the current state of the world when setting up plugins like `gatsby-source-filesystem`, we need them to be configured with a `__dirname` from the user's site (we could have a special `__inTheCurrentSite` value in the future instead).

In the end-user's site, we declare a "theme" using the `__experimentalThemes` keyword in gatsby-config. We use this keyword so that people are aware this functionality is experimental and may change without warning. A theme can be configured in the same way plugins are configured (TODO: change `[theme, config]` syntax to match plugin `{resolve:,options}` form) so that the userland APIs match up.

```js
// gatsby-config.js
module.exports = {
  __experimentalThemes: [[`blog-theme`, { dir: __dirname }]],
}
```

The theme then includes a gatsby-config.js which allows it to defined all of the expected fields, such as plugins, and also configure them based on user input. (TODO: looks like gatsby-config.js is ignored in the .gitignore file for the theme package in commit #2)

```js
// blog-theme gatsby-config.js
module.exports = ({ dir }) => ({
  siteMetadata: {},
  plugins: [
    `gatsby-mdx`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: "blog-posts",
        path: `${dir}/blog-posts/`,
      },
    },
  ],
})
```

### Composing themes

Multiple themes can be used, although there is (intentionally) nothing included in this PR to stop or resolve potential conflicts (for example if a gatsby plugin needs a singleton instance for some reason).

```js
// gatsby-config.js
module.exports = {
  __experimentalThemes: [`blog-theme`, `store-theme`],
}
```

### Themes as plugins

Themes are also included in the plugin list, so they can take advantage of using files such as `gatsby-node`. When being used as plugins, themes receive the full themeConfig as the options object. As an example, a blog theme could be instantiated multiple times on a site, once for blog posts and once for product reviews.

```js
// gatsby-config.js
module.exports = {
  __experimentalThemes: [
    [`blog-theme`, { baseUrl: '/posts' }},
    [`blog-theme`, { baseUrl: '/reviews' }]
  ],
}
```

# etc

##### Commits

This PR contains two commits. The first is the actual functionality, the second is a set of examples (a theme defined as an npm package and an example site using said theme). I expect to remove the second commit before merging, but am open to other approaches to keep an example, etc around and develop it further as we progress.

##### This PR intentionally does not cover:

- Defining data types in any way different than the current sourcing patterns
- Any official sub-theming support for overriding components, etc
  * the only way to "override" things right now is to use gatsby lifecycles (ex: on-create-page hooks) to replace the full page component.
  * still technically possible in user-land, planned but not included in core yet
jedrichards pushed a commit to jedrichards/gatsby that referenced this issue Nov 1, 2018
This is the first step towards gatsby themes. It is low level and defines the way multiple gatsby sites compose by defining the way in which gatsby-config's compose. Everything else will build on top of this composition model so it's important to make it extensible and maintainable for the future.

For those that are mathematically inclined, this defines a monoid for the gatsby-config data structure such that `(siteA <> siteB) <> siteC === siteA <> (siteB <> siteC)`. This makes it nice when thinking about sub-theming in the future (imagine a complex `ThemeA <> subthemeA <> ThemeB <> subthemeB <> user-site` situation)

This method of composition opens the door to themes and sub-themes and allows us to get more user input into how to deal with potentially conflicting artifacts (such as two singleton plugins being defined), test out approaches to generic overriding the rendering of components in user-land, and more.

## Themes

A theme is defined as a parameterizable gatsby site. This means that gatsby-config can be a function that accepts configuration from the end user or a subtheme. This is important because in the current state of the world when setting up plugins like `gatsby-source-filesystem`, we need them to be configured with a `__dirname` from the user's site (we could have a special `__inTheCurrentSite` value in the future instead).

In the end-user's site, we declare a "theme" using the `__experimentalThemes` keyword in gatsby-config. We use this keyword so that people are aware this functionality is experimental and may change without warning. A theme can be configured in the same way plugins are configured (TODO: change `[theme, config]` syntax to match plugin `{resolve:,options}` form) so that the userland APIs match up.

```js
// gatsby-config.js
module.exports = {
  __experimentalThemes: [[`blog-theme`, { dir: __dirname }]],
}
```

The theme then includes a gatsby-config.js which allows it to defined all of the expected fields, such as plugins, and also configure them based on user input. (TODO: looks like gatsby-config.js is ignored in the .gitignore file for the theme package in commit gatsbyjs#2)

```js
// blog-theme gatsby-config.js
module.exports = ({ dir }) => ({
  siteMetadata: {},
  plugins: [
    `gatsby-mdx`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: "blog-posts",
        path: `${dir}/blog-posts/`,
      },
    },
  ],
})
```

### Composing themes

Multiple themes can be used, although there is (intentionally) nothing included in this PR to stop or resolve potential conflicts (for example if a gatsby plugin needs a singleton instance for some reason).

```js
// gatsby-config.js
module.exports = {
  __experimentalThemes: [`blog-theme`, `store-theme`],
}
```

### Themes as plugins

Themes are also included in the plugin list, so they can take advantage of using files such as `gatsby-node`. When being used as plugins, themes receive the full themeConfig as the options object. As an example, a blog theme could be instantiated multiple times on a site, once for blog posts and once for product reviews.

```js
// gatsby-config.js
module.exports = {
  __experimentalThemes: [
    [`blog-theme`, { baseUrl: '/posts' }},
    [`blog-theme`, { baseUrl: '/reviews' }]
  ],
}
```

# etc

##### Commits

This PR contains two commits. The first is the actual functionality, the second is a set of examples (a theme defined as an npm package and an example site using said theme). I expect to remove the second commit before merging, but am open to other approaches to keep an example, etc around and develop it further as we progress.

##### This PR intentionally does not cover:

- Defining data types in any way different than the current sourcing patterns
- Any official sub-theming support for overriding components, etc
  * the only way to "override" things right now is to use gatsby lifecycles (ex: on-create-page hooks) to replace the full page component.
  * still technically possible in user-land, planned but not included in core yet
wardpeet added a commit that referenced this issue Mar 17, 2021
leithonenglish added a commit that referenced this issue Mar 10, 2022
leithonenglish added a commit that referenced this issue Mar 11, 2022
* intiial commit

* canary commit #1

* canary commit #2

* canary commit #3

* tmp

* canary commit #4

* update #4

* update #5

* made sure messages are seen and removed code for idle state

* fixed issue with BUILDING status

* temp

* made sure tooltip stays visible
pragmaticpat pushed a commit to pragmaticpat/gatsby that referenced this issue Apr 28, 2022
pieh added a commit that referenced this issue Oct 26, 2022
pieh added a commit that referenced this issue Oct 26, 2022
mwfrost pushed a commit to mwfrost/gatsby that referenced this issue Apr 20, 2023
axe312ger added a commit that referenced this issue Jul 28, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Issue with a clear description that the community can help with.
Projects
None yet
Development

No branches or pull requests

2 participants