search

gatsbyjs / gatsby

The best React-based framework with performance, scalability and security built in.
https://www.gatsbyjs.com
MIT License
55.29k stars 10.31k forks source link

Next steps for gatsby-theme-blog #16106

Closed KyleAMathews closed 5 years ago

KyleAMathews commented 5 years ago

I've spent ~20 hours over the past week building child themes of gatsby-theme-blog and have some thoughts about ways we can iterate on it.

Thoughts in no particular order.

Making the breaking change for querying seems like the most pressing issue — assuming there's no objections we should do that soon (I could tomorrow). I can also put together a starter for blog sub-themes.

Thoughts for other improvements we could make?

Beyond the above, mostly usability improvements / bug fixes. It'd be good to also think through what additional features we could add to gatsby-theme-blog. Pagination is an obvious one.

KyleAMathews commented 5 years ago

/cc @gatsbyjs/docs @gatsbyjs/themes

amberleyromo commented 5 years ago

I have no objection to the change for querying. +1 for doing it tomorrow, pending others' comments.

Future features: pagination, tags, rss, preset accessible color themes that can be enabled through option setting in the gatsby-config.

johno commented 5 years ago

This all sounds great to me. One thing I'd also maybe bring up for consideration is making the default theme a bit less opinionated in styling. A lot of the theme.js it introduces feels like it could be its own package.

I'd be interested in exploring a theme the mostly used system fonts and a more minimal theme.js to be the default and make our current official theme become another, officially supported, derivative.

ChristopherBiscardi commented 5 years ago

querying change ++. The only potential issue I see is if people are re-using the posts template for other pages... but I'm pretty sure I'm the only one doing that.

There's a lot of things to figure out when starting a new sub-theme.

We should list these points out somewhere.

I've done some preliminary work in the gatsby-theme CLI for stuff that needs to happen (here). I also have a PR in for local themes that passes all the tests. I think because themes are plugins we need to support this, and it could also make instantiating new child themes easier if you're not working in a workspace initially.

It'd be nice to have an automated way to port prism themes to be compatible with theme-ui

Seems like we could do this for a variety of theme styles (vscode, etc).

Make the gatsby-remark-image fix

Leaving a comment on that issue for you @KyleAMathews

Thoughts for other improvements we could make?

A cross-theme Tag data type that can be used to construct tags pages. Notes and Blog should probably both support this, and it would be extensible with user-defined types/other themes could add support.

Pagination is an obvious one.

I don't think pagination is generally useful tbh. Most people don't have enough posts to necessitate paginating across multiple pages, it increases the workload for someone browsing the site, and makes finding posts no longer CMD+f'able. Few people pass the first page of google and how many would pass the first page of some random blog they dropped onto?

ChristopherBiscardi commented 5 years ago

Also maybe search in some way as an add-on plugin? gatsby-plugin-algolia or something that uses BlogPost and Note types? I haven't added search to any of my own sites in a generic way so I'm not sure what this would look like.

(which reminds me we need to do the Note thing for gatsby-theme-notes like we did BlogPost for gatsby-theme-blog)

DavidSabine commented 5 years ago

I'll add to johno's comment about styling. gatsby-theme-blog currently expresses a very strong opinion about how style should be done, and introduces many global-scope decorations (e.g. typography, the pre [or maybe code] HTML tag is modified globally), et cetera.

I have decided to use this theme at //scrum.works/articles --- but to make it work with my existing styling (mostly @emotion and some scss) I've had to unofficially fork gatsby-theme-blog into my own repo and then strip out everything related to theme-ui.

I think two types of people will want to use gatsby-theme-blog: those who want a turnkey readymade blog to kickstart their own gatsby site (and they'll like having some style built-in); and those who have an existing gatsby site and will want to enhance it with blog functionality (and they'll face problems).

Better separation of concerns might look something like this:

gatsby-theme-blog

In my use-case then, I'd simply use gatsby-theme-blog-features and not the cosmetics.

(I'll add, I think the work done is outstanding. And, if I hadn't started a gatsby site 6 months ago, I think I'd really love to start with gatsby-theme-blog and it's approach to cosmetics. I could see myself loving prism, typography, etc. But not everyone who would benefit from gatsby-theme-blog is starting in the same place.)

KyleAMathews commented 5 years ago

This all sounds great to me. One thing I'd also maybe bring up for consideration is making the default theme a bit less opinionated in styling. A lot of the theme.js it introduces feels like it could be its own package.

Discussed this a bit on Slack and we want to move most of the functionality from gatsby-theme-blog into gatsby-theme-blog-core — @ChristopherBiscardi is working on this.

KyleAMathews commented 5 years ago

It'd be nice to have an automated way to port prism themes to be compatible with theme-ui

@jxnblk has a PR up for this https://github.com/system-ui/theme-ui/pull/231

KyleAMathews commented 5 years ago

Also maybe search in some way as an add-on plugin? gatsby-plugin-algolia or something that uses BlogPost and Note types? I haven't added search to any of my own sites in a generic way so I'm not sure what this would look like.

yeeeesssss!

I've played a bit with Algolia's API and this is totally doable. gatsby-plugin-algolia could take options for GraphQL types to sync to Algolia and could even theme-style include a simple search page that works out-of-the-box for people. This would be useful tons of places.

alexluong commented 5 years ago

Hey folks,

This may not be directly in regards to gatsby-theme-blog, but I've been doing some experiments with data abstraction for blogs for the past few days.

I've come up with something quite interesting that I'd like to share with yall and get some feedback.

Objectives

I'm trying to establish a set of standard interfaces (Post, Page, Tag, Category, etc). We can then build a theme ecosystem equivalent to WordPress's. The end goal is that people can choose their own CMS and choose a theme in this ecosystem and have a site ready to go without writing any code.

The way I imagine this, there are a few components:

When users start a site, they will install the UI theme and the adapter theme for their CMS. This should be all the code they need to write to have a site up and running:

// in gatsby-config.js

module.exports = {
  plugins: [
    "ui-theme",
    {
      resolve: "contentful-adapter",
      options: tokens
    }
  ]
}

Once we have these set up, people can start writing UI themes that everyone can use.

Implementation

I've built a proof of concept for this idea.

Here is a quick recap of what I did:

In the repo, there are 5 example sites:

Questions

I'd love to hear what your thoughts on this, and how would this align with what the Gatsby team is doing.

Specifically, is this something you folks would want to make official? Otherwise, I can try to make this a separate project by itself.

I'd love to chat more about this if anyone is interested. Thank you!

NickyMeuleman commented 5 years ago

This all sounds great to me. One thing I'd also maybe bring up for consideration is making the default theme a bit less opinionated in styling. A lot of the theme.js it introduces feels like it could be its own package.

Discussed this a bit on Slack and we want to move most of the functionality from gatsby-theme-blog into gatsby-theme-blog-core — @ChristopherBiscardi is working on this.

Sounds exciting! This was kinda what I was going for with my themejam submission 😅
I want to help if I can. My submission to the themejam has some extra features that MIGHT be useful (like pages for tags, pagination of blogposts)

It'd be nice to have an automated way to port prism themes to be compatible with theme-ui

@jxnblk has a PR up for this system-ui/theme-ui#231

May I suggest @DSchau's awesome work in https://github.com/gatsbyjs/gatsby/pull/15834 to be incorporated at some point in the future? Would be great to have the option to add titles, language tags and a copy button to code blocks.

jletey commented 5 years ago

May I suggest @DSchau's awesome work in #15834 to be incorporated at some point in the future? Would be great to have the option to add titles, language tags and a copy button to code blocks.

@NickyMeuleman I’m currently working hard on making these features part of Theme UI (https://github.com/system-ui/theme-ui/pull/225)! Once they are added, it should be both simple and easy to add these features to ‘gatsby-theme-blog’

ChristopherBiscardi commented 5 years ago

@alexluong Since most of the code in the linked poc there is sourced from either gatsby-theme-blog directly or the code @jlengstorf and myself worked through on the data livestream, it's pretty safe to say we've been thinking about this problem :)

As we discussed on Twitter, there are some outstanding issues preventing this from being the suggested approach for the general population of Gatsby users right now (ex: interface querying by id).

When possible the official themes will be re-implemented as BlogPost and Note interfaces, enabling the (not yet actually named) "adapter" pattern to be used to introduce nodes from different sources.

For next steps on this, I'd highly encourage you to keep experimenting independently; Make sure you check out the Advanced GraphQL techniques livestream to see what else is possible as this will give more insight into where we're headed, watch the gatsby repo for schema customization related PRs which will also keep you on top of the latest developments.

As for your poc, very exciting! I will say that one of the problems with this approach is the amount of additional packages required to get things working. We've toyed with talking about how sources might be able to supply their own generic data adapters to counter this sort of problem. One thing it may be useful for you to look into is how that generic data translation might happen.

That all said, this will be an ongoing concern rather than a "what do we do next for the official themes". An ideal solution wouldn't add any additional new APIs or require significant custom patterns to work.

ChristopherBiscardi commented 5 years ago

@NickyMeuleman I put up a draft PR and tagged you on it (https://github.com/gatsbyjs/gatsby/pull/16166). We can move discussion to there. The current state of the PR is that the core theme works and I'm in the middle of moving gatsby-theme-blog to rely on it. Need to do some shadowing to make sure we don't break current consumers of the theme.

Also please don't let this stop you from submitting to the theme jam! Would love to see what you came up with!

eclectic-coding commented 5 years ago

Love the direction of this conversation. I have been experimenting with themes since they were stable and I clearly can see the long term benefit. However, IMHO right now they are opinionated, especially with styling. I love the idea of a core and adding features as needed.

One feature I would like to see available would be draft mode filters in the BlogPost query in gatsby-node or some other implementation for sites to have available for MDX files.

Just some thoughts from a new (less than six months) developer with React/Gatsby.

ChristopherBiscardi commented 5 years ago

It's likely that -core theme will end up being a reasonably minimal implementation of the BlogPost, etc interface and that we'll try to figure out what the best story for extending those types is, so that pagination, drafts, etc can be extensions to the core rather than built ins

eclectic-coding commented 5 years ago

I totally agree @ChristopherBiscardi ... its so exciting.

pomber commented 5 years ago

Hey, I'm new to gatsby so I may be missing something, but I'm not a fan of the mdx flag that many themes are using.

If I'm using gatsby-theme-a and gatsby-theme-b and both use mdx my gatsby-config.js will look like: 

module.exports = {
  plugins: [
    { resolve: "gatsby-theme-a" },
    { resolve: "gatsby-theme-b", options: { mdx: false } },
  ],
}

But maybe both theme-a and theme-b require specific remark-plugins or something so I need to do:

module.exports = {
  plugins: [
    { resolve: "gatsby-theme-a", options: { mdx: false } },
    { resolve: "gatsby-theme-b", options: { mdx: false } },
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        remarkPlugins: [require(`remark-for-a`), require(`remark-for-b`)],
      },
    },
  ],
}

Which kind of breaks the theme abstraction.

Any ideas to make theme configs more mergeable?

ChristopherBiscardi commented 5 years ago

@pomber Yeah, we're planning on making it so that plugins can implement a new lifecycle called something like onPluginOptions and they can specify how to merge the options from each instance if they, like gatsby-plugin-mdx, require that they have only one instance. At that point this flag will go away and the mdx plugin will be transparent to the end user.

johno commented 5 years ago

Another thing we could do to improve the initial DX, especially for newcomers, is to proxy the theme shadowing from the root of gatsby-theme-blog's src. So that way if a user wants to customize the theme.js they don't have to know about gatsby-plugin-theme-ui.

// gatsby-theme-blog/src/theme.js
export default {
  // ...
}
// gatsby-theme-blog/src/gatsby-plugin-theme-ui.js
export { default } from '../theme'

This wouldn't be a breaking change, but I'd be interested if folks think this is an improvement or a level of indirection.

ChristopherBiscardi commented 5 years ago

@johno I think this would be even more confusing in the case of putting multiple themes together (which theme.js do you shadow? why isn't X theme.js applying in Y location?)

ChristopherBiscardi commented 5 years ago

gatsby-theme-blog-core PR is just about ready. If anyone has comments about the general structure/separation of plugins, etc now is the time!

https://github.com/gatsbyjs/gatsby/pull/16166

ChristopherBiscardi commented 5 years ago

Changes that are now live:

Open questions:

ChristopherBiscardi commented 5 years ago

I think everything here has either it's own issue or is published already. Going to close this mega-issue in favor of the smaller, more actionable ones. Thanks for the feedback everyone!

swyxio commented 5 years ago

what's @johno's approach? got a link?

DavidSabine commented 5 years ago

Huge thanks to everyone who pulled this off. I implemented gatsby-theme-blog-core, and applied my site's cosmetics, easily within an hour this evening. https://scrum.works/articles/

I love the simplicity of this approach. I had to shadow only two files (post.js and posts.js) to seamlessly produce a beautiful blog.

Many thanks and congratulations.

johno commented 5 years ago

what's @johno's approach? got a link?

It's currently tossed into a branch on a "scratch" repo. You can see the CLI source code here.

The idea around this approach (I'll likely break this out into an issue today for further discussion):

Something that I noticed with the child theme workflow is that starting from gatsby-theme-blog (for themes that wanted more customization and creative freedom than changing a couple things) are forced into a lot of "unsetting" gymnastics. This DX was a bit clunky so I began thinking about a preferred workflow might be opting to start from the data (blog-core) and using that as the base theme for working on a theme's presentation.

Chris is likely referring to that where I'm currently exploring workflows to optimize "building" from the data and scaffolding out a standard/predictable component structure (that will work for most usecases). This has the potential to give folks more creative freedom in their themes while still avoiding some initial boilerplate of scaffolding out components (there are really only so many variations to blog layout, headings, and navigation).

Right now, it's a half-baked CLI utility that allows you to choose a couple of templates for layout, navigation, etc. and it will write out your initial component files for a gatsby-theme-blog-core child theme.

A tweet I made with a video illustrating this experimental workflow.

While we figure out the best abstractions for things like layout (especially with Theme UI), I want to make it easy to work without an abstraction :smile_cat: and let the data drive the presentation.

Another thing I noticed was that when building a theme that's intended to work well with shadowing, one typically wants more granularity in components than is currently available in gatsby-theme-blog. This allows finer-grained shadowing to customize individual components and even layout (like PostList and Post wanting different navigation structures). This is interesting because it's contrary to how many would normally build a component (colocate all the things, break it later). This CLI tool can be potentially used to help establish this pattern.

swyxio commented 5 years ago

cool. if i have one request it is that could you consider namespacing all data ingestion (and consumption) to make life a lot easier for us downstream. right now too much of gatsby data consumption is greedy af, aka "if its a markdown file it's mine!!!! regardless of where it came from!!!" which is fine if you control gatsby-node, but it makes themes very annoying/pointless to use together (or to use multiple instances of the same theme). this is because either by accident or design we barely check sourceInstanceName when actually creating pages. but same rule could apply for basically any other source data.

i swear i'm not randomly picking on this one thing, i genuinely believe this is a foundational design antipattern that gets in the way of themes reaching your vision.

johno commented 5 years ago

Yeah I hear that, I believe this is something we're (partially) addressing with the BlogPost type, right?

Maybe I'm misunderstanding but the type is defined by the theme and then sourceInstanceName is checked before node creation to ensure we can cleanly query allBlogPost without having to operate on File. Or are you more referring to the plugin level?

gatsby-plugin-mdx still operates globally on all Markdown nodes which can introduce issues as well when multiple themes bring that plugin (which is something that definitely still needs to be addressed).

swyxio commented 5 years ago

ah yes this is the kind of thing i'd like to see in all themes for them to interop. hopefully we'll find a better api or util library that introduces a type and customizes schema out of the box as this is going to be best practice.

interesting point about gatsby-plugin-mdx being global, i guess i hadnt thought enough about that. i'm sure you'll figure it out.

trevordmiller commented 5 years ago

"I'd be interested in exploring a theme the mostly used system fonts and a more minimal theme.js to be the default and make our current official theme become another, officially supported, derivative."

This would be awesome!