Starter Showcase

[swyxio]

demo: https://gatsby-starter-search.netlify.com/
repo: https://github.com/sw-yx/gatsby-starter-search

related links: #4392

twitter discussion: https://twitter.com/gatsbyjs/status/993954935489282048

I started doing some work on this without knowing there was a Example showcase going on.

(esp didn't know there was a screenshot transformer lol)

this is a rough cut of what I've done. just using an existing design I had lying around, didn't optimize for @fk's beautiful work but I have some nice things like filter by dependencies (can obviously tighten this up a lot but I've only worked on this one afternoon)

---

edit from the future

the PR into the main docs is here: #6113 (previously #5831)

preview at https://dreamy-shannon-191f15.netlify.com/starter-showcase/

[KyleAMathews]

I'd rather keep the source of truth here. For the site showcase, we moved to a YAML file which would great to copy as we can enforce a proper schema.

[swyxio]

ok to be clear the yaml file is just this proposed format https://gist.github.com/fk/5ec0dbdaeb7f4e1839c99b18cbd42332 ?

I can give comments there but I think the stuff that can be autogenerated like the plugins list should be autogenerated.

real talk tho is the starter showcase just the subset of the site showcase that is open source? (probably not). Is it just the subset of the site showcase that is explicitly tagged with a "starter" category? is it not a subset and a conceptually different thing?

I ofc don't want to compete/confuse with anything you're trying to do. I just didn't like the current starter browsing experience.

cc @shannonbux for ideas/direction.

[KyleAMathews]

The starter showcase is going to replace the existing starters page. So completely separate from the site showcase — though it'll almost certainly share a lot of design ideas / components.

And yeah, that's the format — it's in the repo now at https://github.com/gatsbyjs/gatsby/blob/master/www/src/data/sites.yml

[shannonbux]

Exactly what @kylemathews said; the starter and site showcases will be separate, although the two ought to share design ideas and components (to save time and create a consistent user experience). Have you checked out the progress on the site showcase too? This is awesome that you're working on this, Shawn!!!

…

On Wed, May 9, 2018 at 10:22 AM, shawn wang ***@***.***> wrote: ok to be clear the yaml file is just this proposed format https://gist.github.com/fk/5ec0dbdaeb7f4e1839c99b18cbd42332 ? I can give comments there but I think the stuff that can be autogenerated like the plugins list should be autogenerated. real talk tho is the starter showcase just the subset of the site showcase that is open source? (probably not). Is it just the subset of the site showcase that is explicitly tagged with a "starter" category? is it not a subset and a conceptually different thing? I ofc don't want to compete/confuse with anything you're trying to do. I just didn't like the current starter browsing experience. cc @shannonbux <https://github.com/shannonbux> for ideas/direction. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5334 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2tpkVqB6y0SrMwEV3UgqgsHCS9NPks5twyXEgaJpZM4T3Xea> .

[swyxio]

ok if the site showcase is more important I'll just put this thing on hold. I think it makes sense to finish one out first and then ctrl+c ctrl+v to the other (obv I have a preference for starting with starter but 🤷‍♂️ ).

I'll comment further on the site showcase issue regarding that stuff.

fwiw I did this on my own without even knowing you were doing this work, this is great and I feel the Gatsby docs are coming along very nicely thanks to you both. I don't know that I can commit to significant amounts of time on this.

[shannonbux]

Here's a summary of what insights I've gotten from interviewing Gatsby users:
Pain points according to interviews on this topic (see attached PDF for full quotes):

• People sometimes don't know what starters or Gatsby sites exist
• One interviewee installed several starters that were disappointingly ugly, and he wishes the documentation was more thorough so he knew what he was getting into.
• Some starters are outdated
• People often learn what's possible to build and how to build it by looking at src code for other starters / sites.

Potential benefits of bringing a site / starter showcase (also based on interviews):

• Persuading more people to use Gatsby: People will have confidence that they can imitate what's already been built if they see it and can look at the src code. It would also be cool to have a way of demonstrating that the development experience was awesome. Stories of how quickly they built the sites, or how big the team was, etc. Just to give ppl more motivation and confidence that they can repeat the same process and have a successful result.
• More highly functional Gatsby sites out in the world: Many people learn how to build things by looking at src code for other sites. The more sites they can explore the code for, the more likely they are to learn how to build equally functioning sites.
• Ways of showing not only finished results but also development experience of Gatsby: People want a showcase of how quickly you can create a site
• A way of showing how plugins perform, since many plugins have a visual or performance result that can only be fully experienced by seeing it in practice

Starters.pdf

[shannonbux]

Here's the MVP and a few ideas of future enhancements (MVP shares a lot with site showcase w/ a few changes):

MVP (minimum viable product)
Users should be able to:

• See what starter looks like (for site showcase we use screenshots; don't know if that'd work for starters)
• Install starter quickly
• See source code of starter
• Share starter
• Filter by category
• Filter by functionality (does this include more than dependencies?)
• Search by keyword
• Submit their own starter to the showcase through yaml file (Shannon writes the instructions)
• See a list of the starter's dependencies

Nice to have
It would be nice if users could:

• See featured starters (not strictly MVP, might be worth it anyway)
• personal page for creators of starters (see all starters they have submitted)
• Sort by date added (won't matter until ppl start submitting starters) and popularity, filter by category or tag (filtered index page)
• Share sites with a social media / URL copy button in a modal
• See sites built with that starter
• Read about each starter's creator (bio)

Very cool, not necessary right away
It'd be awesome if users could:

• See the performance of starters in action (if they have functionality with a visual component, ex. GIFs, performance metrics, data on traffic improvement after the site switched to Gatsby,etc.)
• See a list of all starters that use a particular plugin (this would be a change to the plugin library, probably)
• Sign up to get notifications or updates when new starters are added (or just sign up for the newsletter?)
• Click on links to relevant tutorials and docs from each starter

[swyxio]

@shannonbux this looks great - I think I can handle a bunch of these. How much do you want to involve Florian or should I just get cracking and stick as close as possible to the Site Showcase design? can looking too similar to the Site Showcase be a problem?

[tsiq-swyx]

got started on this today, have the main page up and kinda working, now on the details page

[m-allanson]

An idea for a feature (via @hughpearse, #5847) that I couldn't see listed here: add a "Deploy this starter" link or button that publishes the starter to Netlify.

@LekoArts noted that this might be redundant in some cases, as starters will often have that button in their readme.md file.

[fk]

Here's a rough mock for the index page with a slightly adjusted showcase design including all meta information currently shown at https://gatsby-starter-search.netlify.com/:

• "open in new window/launch" icon opens the demo, GitHub icon links to the repository
• GitHub username got its own line
• not sure if we should show "Tags" for each starter card or not
• "78 Starters to jump-start your new website" 🙄 ;)

[fk]

And another even rougher one for the permalink/detail/modal:

• very prominent "Try this starter on" deploy buttons—position is fine, but they're very clunky still; I'm assuming that we won't start off with more than the three buttons shown, probably only two, so that's fine for now; for more than that, we could
  • move them out of the header
  • fall back to just displaying the icons (along with a tooltip or revealing the full button on hover)
  • add a dropdown… 🙄
• added a drop shadow to the starter image to set it off against the background; will experiment with this
• idea, not sure if it's a good one: we could (just or along the yaml short_description and description) show the README of the package
• omitted prev/next links here, but could be similar to the site showcase UI

[LekoArts]

not sure if we should show "Tags" for each starter card or not

I like the simplicity and would suggest not including the tags on the cards. If you filter/search via your tags the result on the right side should speak for itself, especially if you use multiple tags to narrow down the choices.

idea, not sure if it's a good one: we could (just or along the yaml short_description and description) show the README of the package

Looking at your example you see one problem with including the original README:
If the README includes images, gifs etc. it's duplicate content with the header image.

Would be cool to encourage the creators to write an extra description specific to this starter page.

[fk]

Hey Lennart, cool you're hanging around here. Appreciate your input!

👍 to not showing tags for each starter card…and yeah, let's go with showing the description from the yaml, including the README at least clearly needs more thought. ;)

[LekoArts]

Ah, and to quote myself:
If the README would include a "Deploy to Netlify" it would be duplicate content, too 😆

very prominent "Try this starter on" deploy buttons—position is fine, but they're very clunky still; I'm assuming that we won't start off with more than the three buttons shown, probably only two, so that's fine for now; for more than that, we could
move them out of the header

Agree. Moving them between preview image and description would be a good fit I guess. Hover/Dropdown is more like an emergency plan to me.

[tsiq-swyx]

Would be cool to encourage the creators to write an extra description specific to this starter page.

just want to point out that im going with individual markdown files for the starters (im being a little bit stubborn about this one for now) instead of a giant yaml file so it is absolutely possible to write the extra description in the body of the markdown file when submitting. was one of my original design goals.

i'm going to choose not to care about the duplication problem for now. its something we can deal with after we deploy an mvp

[tsiq-swyx]

@fk thinking this through another nice to have would be a "copy to clipboard" feature on both the master and detail pages that copies a gatsby new [url] prefilled in it

[tsiq-swyx]

made more PR's and its basically usable now. needs review from shannon

[tsiq-swyx]

hey @LekoArts check out your sites: https://dreamy-shannon-191f15.netlify.com/starter-showcase/?s=lekoarts

feedback welcome.

[tsiq-swyx]

copying and pasting my notes on remaining polish/todo list - this is a repeat of the internal issue, but may or may not be updated so dont rely on this. just trying to give open source watchers an idea

---

relevant links:

• original starter showcase issue: Starter Showcase #5334
• I have a first draft up awaiting review from fk and shannon: https://dreamy-shannon-191f15.netlify.com/starter-showcase/?sort=stars

Here are the remaining things from @shannonbux 's requirements lists:

• See featured starters? swyx: I just think we should have a few really good officially maintained starters
• personal page for creators of starters (see all starters they have submitted) swyx: could be handy for agencies that want to promote themselves off Gatsby
• Read about each starter's creator (bio) swyx: ditto
• Share sites with a social media / URL copy button in a modal swyx: I think this is done but shareability could always be better
• See sites built with that starter swyx: not possible but some review functionality would be nice
• See the performance of starters in action (if they have functionality with a visual component, ex. GIFs, performance metrics, data on traffic improvement after the site switched to Gatsby,etc.) swyx: basically want case studies
• See a list of all starters that use a particular plugin (this would be a change to the plugin library, probably) swyx: love this, its low hanging fruit
• Sign up to get notifications or updates when new starters are added (or just sign up for the newsletter?)
• Click on links to relevant tutorials and docs from each starter

my thoughts on technical things to do:

• move images from /static to image source consumption so we can use gatsby-image?
• algolia search instead of simple filter�?
• discuss whether we need to move from individual .md format to single .yml like the site showcase. (my intuition is no)
• consider fully automating the GitHub scraping as part of the www build process (might need to fiddle with some things on the netlify side)
• (minor) fix the build time repository warning in the GitHub scraper.
• discuss: whether and how to display the starter's README (we punted on it for mvp and I just went with GitHub description)
• discuss: infinite scroll instead of "load more" button
• discuss: design empty state https://gatsbyjs.slack.com/archives/CB4V648ET/p1529262477000070

other ideas:

• discuss how to handle some starters that don't look great but have good functionality. Ideally want to guide people away from merely judging a book by its cover for some starters.
• add a review system (ideally want this outside GitHub issues, can host on firebase)
• let people list premium starters, help them sell for $? need a separate pipeline for private repos
• tutorial on how to make a starter (we should also just clarify there's very little magic in the concept of starters... for now)
• standalone Gatsby plugin/starter API for us to ping but also for code sandbox/guppy/etc to pull in data

[LekoArts]

@tsiq-swyx Feedback on what exactly?

• It's not all of my starters, I have some more
• The screenshot for "emilia" and "emma" isn't really showing how the page actually looks. Can that be fixed?
• The icons in the overview (right of my name) shouldn't have an underline

[tsiq-swyx]

@LekoArts - i have updated your starters, thanks for reviewing. also did the icons. you can check it again! https://dreamy-shannon-191f15.netlify.com/starter-showcase/?s=lekoarts

---

separately - added version warnings to help prevent people using old starters

[LekoArts]

Do you want feedback on the mobile version or are you aware of the issues?

I‘d put the Gatsby version in the detail view, not overview. Firstly v1 isn’t outdated yet, secondly even if the starter uses the old version migrating from v1 to v2 isn’t that hard.

How about making the repository names also links to the detail view? I always click the name first before realizing that I have to click the image.

[swyxio]

well fwiw I will wait for #5927 to be finished first since I am taking my design cues from there. I had no design spec for mobile at all so didn't spend much time on it. also (personally speaking) mobile view is less important to me because starter showcase is most likely for desktop (so I care more that it "looks fine on mobile" than having full functionality)

I think you have a point about the version in detail view. this was something I decided, wasn't in the design spec, and I can easily move it. will discuss with @shannonbux and go with whatever she decides. the reason I put it in overview, is I want to heavily encourage starter maintainers to upgrade to v2. "migrating from v1 to v2 isn't that hard" but I prefer people who are totally new to Gatsby start off on the right foot by using v2.

the name thing - ok. easy.

[LekoArts]

I'm sure @fk will make a mobile view for reference.

also (personally speaking) mobile view is less important to me because starter showcase is most likely for desktop (so I care more that it "looks fine on mobile" than having full functionality)

It would be dangerous to ignore mobile users! Most websites have equal mobile traffic or sometimes even more mobile users than desktop users.

the reason I put it in overview, is I want to heavily encourage starter maintainers to upgrade to v2. "migrating from v1 to v2 isn't that hard" but I prefer people who are totally new to Gatsby start off on the right foot by using v2.

It's fine that you want to encourage the maintainers but in my opinion you're telling users (especially with the red color) that these starters are unusable which is not the case. Until v2 is out of beta both versions are equal to me.
When v2 is officially out you could give an option to sort via v1 and v2 while picking v2 as a default. So if maintainers want their starters to appear in the overview (without the user to manually check another checkbox) they'll need to upgrade. This "graceful" transition could be done for some time and after a while you'd just remove all v1 starters for example.

[fk]

Here's the link to the clickable prototype for mobile I posted a while ago: https://projects.invisionapp.com/share/T9H9LRCG8Z5#/screens/292717380_Index

It's also contained within the Sketch file: https://www.dropbox.com/s/9vzatfift5oz69b/gatsbyjs.org%3Ashowcase.v2.sketch

[swyxio]

fwiw Leko i -never- said i was ignoring mobile users :)

[swyxio]

Things done to v2 PR (#6113) after @kkemple's refactor (Issue: #5927, PR: #6095):

• refactor to match kkemple's file structure
• make the mobile view work
• cumulative filtering

How the mobile view looks now