diff --git a/README.md b/README.md index a8ef122fbd842..ed0f77d511fea 100644 --- a/README.md +++ b/README.md @@ -277,7 +277,7 @@ Websites built with Gatsby: **[View the docs on gatsbyjs.org](https://www.gatsbyjs.org/docs/)** -[Migrating from v1 to v2?](https://www.gatsbyjs.org/docs/migrating-from-v1-to-v2/) +[Migrating from v1 to v2?](https://next.gatsbyjs.org/docs/migrating-from-v1-to-v2/) [Migrating from v0 to v1?](https://www.gatsbyjs.org/docs/migrating-from-v0-to-v1/) diff --git a/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md b/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md index 8a07ad5a491d3..67d15595ce58f 100644 --- a/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md +++ b/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md @@ -53,7 +53,7 @@ need to maintain a runtime, a database, application code, or complex optimized web servers. But the downside is you have to keep separate template files that will -eventually rendered as HTML on the browser, and Javascript file that will +eventually rendered as HTML on the browser, and JavaScript file that will eventually manipulate that HTML again on the browser (and CSS assets too). ## Enter the new world order @@ -86,7 +86,7 @@ On your end, the development flow looks: - During development, write code like a boss (hot reloading, modularized code, webpack plugins, etc...) - Use React.js Server Side Rendering API to convert this code to static HTML - content, and Javascript code, on your server + content, and JavaScript code, on your server It’s really that easy? Well, sort of. diff --git a/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md b/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md index a586d1274f90f..3a63f7d84fcb2 100644 --- a/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md +++ b/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md @@ -157,7 +157,7 @@ features. I haven’t heard any complaints from my co-workers. Another “problem” with static sites is the lack of out-of-the-box site search. Most search implementations occur between the server and the database. As a doc site, users typically expect solid search functionality. There are a few -frontend only javascript search libraries (like [lunr.js](https://lunrjs.com/)) +frontend only JavaScript search libraries (like [lunr.js](https://lunrjs.com/)) that take a search query and parse a pre-built JSON index of your content. I could have created this index by tying into the `onPostBuild` Gatsby API. This diff --git a/docs/blog/2018-02-16-bright-future-for-the-web/index.md b/docs/blog/2018-02-16-bright-future-for-the-web/index.md index 4494e5cc862cf..0f206624e428b 100644 --- a/docs/blog/2018-02-16-bright-future-for-the-web/index.md +++ b/docs/blog/2018-02-16-bright-future-for-the-web/index.md @@ -10,7 +10,7 @@ _This article was originally published on [Medium](https://medium.com/@ryanwiemer/gatsby-and-the-jam-stack-91e31508f364) on January 31, 2018._ -Recently I relaunched my wife’s photography portfolio, [KNW Photography](https://www.knw.io/), using a combination of Gatsby, [Contentful](https://www.contentful.com/) and [Netlify](https://www.netlify.com/). This particular group of tools represents a new and exciting web development architecture known as the [JAMstack](https://jamstack.org/) (Javascript, APIs and Markup). In this post I will be sharing my personal thoughts on each of these new tools and why together they represent the “holy grail” of the static website world. +Recently I relaunched my wife’s photography portfolio, [KNW Photography](https://www.knw.io/), using a combination of Gatsby, [Contentful](https://www.contentful.com/) and [Netlify](https://www.netlify.com/). This particular group of tools represents a new and exciting web development architecture known as the [JAMstack](https://jamstack.org/) (JavaScript, APIs and Markup). In this post I will be sharing my personal thoughts on each of these new tools and why together they represent the “holy grail” of the static website world. ## Why Other Static Site Generators Didn’t Work For Me diff --git a/docs/blog/2018-03-29-migration-from-wordpress-to-gatsby/index.md b/docs/blog/2018-03-29-migration-from-wordpress-to-gatsby/index.md index 832c452e913c3..78c3b13477815 100644 --- a/docs/blog/2018-03-29-migration-from-wordpress-to-gatsby/index.md +++ b/docs/blog/2018-03-29-migration-from-wordpress-to-gatsby/index.md @@ -32,9 +32,9 @@ Long story short, I decided to get rid of WordPress and replace it with a much m JAM is an acronym for **J**avascript **A**PI **M**arkup. What does it mean though? It is not a framework or a specific technology. It is more of an architectural approach. A modern way web content is built, managed and distributed. -Back in the day, the web was just static HTML pages, maybe with some CSS and Javascript on the top. Perfect for static content. However, usually, you need your data to be more dynamic. Instead of static HTML sitting on the server served directly, HTML pages were built on-the-fly when a client requested them. The data dynamically provided from a database. While this is very flexible, it comes at a cost. It's slow. Way slower than just a static site. The application server executes code on demand, needs to contact a database, usually on a different machine, build the page and send it back. The scalability is hard and expensive. When the traffic rises, its more complicated to scale the solution. We're talking load balancing, session replication, distributed caching not to mention difficult RDS scalability. And it's vulnerable. With so many moving parts, the attack surface is extensive. Ranging from Cross-Site-Scripting, SQL Injection to exploiting [security vulnerabilities in your libraries](https://www.vojtechruzicka.com/snyk-detecting-dependencies-with-known-vulnerabilities/). +Back in the day, the web was just static HTML pages, maybe with some CSS and JavaScript on the top. Perfect for static content. However, usually, you need your data to be more dynamic. Instead of static HTML sitting on the server served directly, HTML pages were built on-the-fly when a client requested them. The data dynamically provided from a database. While this is very flexible, it comes at a cost. It's slow. Way slower than just a static site. The application server executes code on demand, needs to contact a database, usually on a different machine, build the page and send it back. The scalability is hard and expensive. When the traffic rises, its more complicated to scale the solution. We're talking load balancing, session replication, distributed caching not to mention difficult RDS scalability. And it's vulnerable. With so many moving parts, the attack surface is extensive. Ranging from Cross-Site-Scripting, SQL Injection to exploiting [security vulnerabilities in your libraries](https://www.vojtechruzicka.com/snyk-detecting-dependencies-with-known-vulnerabilities/). -When you just have static HTML, CSS and Javascript files, it's much harder to compromise your site unless someone gains complete access to your server. Since the content does not change, it is easy to cache. Instead of having just one central server or just a few of them in an expensive and complicated solution, you can use Content Delivery Network to distribute your site. This way you'll have your availability covered and CDN redistributing your files across the globe. Users from New York will be served as fast as users from Tokyo. And if your traffic skyrockets, it is still not a problem. Scalability is easy and cheap if you don't have to manage synchronization of state. +When you just have static HTML, CSS and JavaScript files, it's much harder to compromise your site unless someone gains complete access to your server. Since the content does not change, it is easy to cache. Instead of having just one central server or just a few of them in an expensive and complicated solution, you can use Content Delivery Network to distribute your site. This way you'll have your availability covered and CDN redistributing your files across the globe. Users from New York will be served as fast as users from Tokyo. And if your traffic skyrockets, it is still not a problem. Scalability is easy and cheap if you don't have to manage synchronization of state. ![jam stack](./jamstack.png) diff --git a/docs/blog/2018-04-04-gatsby-contentful-starter-tutorial/index.md b/docs/blog/2018-04-04-gatsby-contentful-starter-tutorial/index.md index dfab371a6efbd..0ab27cf12e78b 100644 --- a/docs/blog/2018-04-04-gatsby-contentful-starter-tutorial/index.md +++ b/docs/blog/2018-04-04-gatsby-contentful-starter-tutorial/index.md @@ -116,6 +116,6 @@ Contentful ensures your website and its users can access your content quickly an That’s a quick overview of how to get your website up and running from scratch using Contentful and GatsbyJS. -Contentful's platform offers speed, flexibility, and ease of integration with your code, supporting any stack you use with SDKs for common languages like [Javascript](https://www.contentful.com/developers/docs/javascript/sdks/), [Python](https://www.contentful.com/developers/docs/python/sdks/), and [PHP](https://www.contentful.com/developers/docs/php/sdks/). Unlike a CMS, Contentful provides you with separation between content and presentation, allowing you to focus on developing your website and leave content delivery to Contentful. +Contentful's platform offers speed, flexibility, and ease of integration with your code, supporting any stack you use with SDKs for common languages like [JavaScript](https://www.contentful.com/developers/docs/javascript/sdks/), [Python](https://www.contentful.com/developers/docs/python/sdks/), and [PHP](https://www.contentful.com/developers/docs/php/sdks/). Unlike a CMS, Contentful provides you with separation between content and presentation, allowing you to focus on developing your website and leave content delivery to Contentful. If you're curious to learn more about Contentful, you can check out the Contentful [Developer Center](https://www.contentful.com/developers/docs/) to learn more on how the technology works, or head over to the [Guides and tutorials](https://www.contentful.com/guides/) section. diff --git a/docs/blog/2018-06-08-life-after-layouts/index.md b/docs/blog/2018-06-08-life-after-layouts/index.md index f595637c8dac3..bb0e257a709a1 100644 --- a/docs/blog/2018-06-08-life-after-layouts/index.md +++ b/docs/blog/2018-06-08-life-after-layouts/index.md @@ -83,7 +83,7 @@ In short, the decision to remove layouts was part of an effort to reduce unneces ### What was the unnecessary complexity? -Because layouts in V1 were applied under the hood, it made it _really hard_ to pass data between the layout the pages it wrapped. +Because layouts in V1 were applied under the hood, it made it _really hard_ to pass data between the layout and the pages it wrapped. In short, layouts in V1 broke React's compositional model, and that made things unnecessarily hard to implement. By going back to the standard React way of importing components and using them directly, we're able to easily pass data between the layout and pages without any confusing, complicated, or otherwise unwieldy workarounds. @@ -93,7 +93,7 @@ In V1, if something breaks on your page, you'd likely go to the page, look throu Because Gatsby is doing things in the background, out of sight of the developers building the site, we're creating a mystery: where the hell did this bug come from if all the code I can see doesn't have the bug? -By removing the magic and making layouts an explicity dependency in V2, that same bug would be much easier to spot because there's a clear link between our page code and the layout. +By removing the magic and making layouts an explicit dependency in V2, that same bug would be much easier to spot because there's a clear link between our page code and the layout. ### Why is this better? diff --git a/docs/blog/2018-06-18-moving-from-create-react-app-to-gatsby-js/index.md b/docs/blog/2018-06-18-moving-from-create-react-app-to-gatsby-js/index.md index 5c30470a2d356..710df81c0ef0f 100644 --- a/docs/blog/2018-06-18-moving-from-create-react-app-to-gatsby-js/index.md +++ b/docs/blog/2018-06-18-moving-from-create-react-app-to-gatsby-js/index.md @@ -22,7 +22,7 @@ If you came across [Gatsby](https://github.com/gatsbyjs/gatsby) you will notice ![gatsby-logo](https://images.ctfassets.net/4x6byznv2pet/4OW1X9ex1mImko8G4w4WAK/a16fceab310b718c7f375a760c4e1e16/logo-gatsby-0603eb9dd6bdfec9599dbc7590f891be-347ea.jpg) -Gatsby is a blazing fast static site generator for [React](https://github.com/facebook/react). Actually, it is more than that. Think of it as a PWA (Progressive Web App) framework with best practices backed in. For example: you get code and data splitting out-of-the-box. +Gatsby is a blazing fast static site generator for [React](https://github.com/facebook/react). Actually, it is more than that. Think of it as a PWA (Progressive Web App) framework with best practices baked in. For example: you get code and data splitting out-of-the-box. ## Why Move to Gatsby? @@ -126,7 +126,7 @@ class BlogPost extends Component { componentDidMount() { getBlogPost(this.props.match.slug) .then((data) => this.setState({ data })) - .catch((error) => this.setState({ state: 'error' })) + .catch((error) => this.setState({ status: 'error' })) } render() { if (!this.state.status === 'error') { diff --git a/docs/blog/2018-06-24-investigating-gatsby-build-performance-at-scale/index.md b/docs/blog/2018-06-24-investigating-gatsby-build-performance-at-scale/index.md new file mode 100644 index 0000000000000..33cb4c147b9ff --- /dev/null +++ b/docs/blog/2018-06-24-investigating-gatsby-build-performance-at-scale/index.md @@ -0,0 +1,55 @@ +--- +title: Investigating Build Performance At Scale +date: "2018-06-24" +author: "Sam Bhagwat" +tags: ["scalability", "builds"] +--- +When website teams are deciding whether to migrate an existing site over to Gatsby, one consideration is how long it takes to rebuild each site when code or content changes. + +In order to help teams evaluate this, we’re publishing a set of build time benchmarks. + +# Performance Considerations + +Generally speaking, Gatsby build times consist of two factors -- O(1) constant-time operations, such as connecting to remote APIs, and O(n) linear-time operations, such as processing markdown pages, transforming images, and so on. + +On smaller sites, O(1) constant time operations take up most of the time “cost” of building a Gatsby site. On larger sites, O(n) linear-time operations predominate. Generally, larger sites tend to be CPU-bound rather than I/O-bound, so a more powerful server, VM, or container will finish quicker. + +The three most memory-intensive operations that scale with site size are **processing markdown**, **creating pages**, and **processing images with gatsby-image**. + +# Benchmark Parameters + +_Site tests_ + +In order to measure the “build performance cost” of each of these three factors, we’ve benchmarked Gatsby build times for two different sites, one image-heavy and one markdown-page heavy. + +The first site is [FreeCodeCamp’s Guide](https://github.com/freeCodeCamp/guide), one of the largest open-source Gatsby sites with around 3,000 pages. The second site is the using-gatsby-image official example [copied into its own repo](https://github.com/calcsam/gatsby-image-performance-benchmarking). We’ve run two different versions of this: first, with around 25 images and second, with around 250 images. Both sites are running on Gatsby v2. + +Note that **using gatsby-image is not a requirement to use Gatsby**. If you have enough images that image-processing-driven build times is impeding project goals or team workflows, consider simply removing (or not implementing) gatsby-image. + +_Machine types_ + +Tests were run on three different machines; on a local development machine (2015 Macbook Pro), on an AWS t2 micro free tier instance, and an AWS memory-optimized m4 instance. + +_Cold start vs warm start_ + +Tests were run both with (“warm start) and without (“cold start”) a pre-existing, local Gatsby cache. + +In most cases when code changes and all cases when content changes, Gatsby will preserve the cache from your previous build, giving you a warm start. The cache is only invalidated in rare instances, for example when the plugin changes. + +Whether you’re able to access the cache from previous builds depends on your CI setup, but many CI providers offer the option of preserving the previous build cache. + +# Results + +For cold start builds, each additional markdown page adds around **0.17 seconds**, while each additional image processed with gatsby-image adds **between 1.5 and 2.1 seconds** to fresh Gatsby builds. + +For warm start builds, each additional markdown page adds **around 0.07 seconds**, while additional images processed with gatsby-image are free. + +Full results are [linked](https://docs.google.com/spreadsheets/d/1ki5PwVTnIyycsk800DSWIA72UAr1k1DUJnKCf_lWz4c/edit#gid=0), along with our [build script](https://gist.github.com/calcsam/4aa066a46d74b6713c053a6adc0e0f76). + +# Next steps + +Gatsby users report that Gatsby builds fail due to running against hard Node.js process memory limits somewhere around 10,000 to 15,000 pages on v1. + +Since v2 has improved memory usage, we want to update this number, as well as further quantify the boundary so that teams considering migrating larger sites to Gatsby have more information for their decision-making. + +We also want to benchmark v2 build performance against v1 build performance for various sites. diff --git a/docs/blog/2018-06-26-card-sort-results/building-apps-with-gatsby.png b/docs/blog/2018-06-26-card-sort-results/building-apps-with-gatsby.png new file mode 100644 index 0000000000000..3e28497106e17 Binary files /dev/null and b/docs/blog/2018-06-26-card-sort-results/building-apps-with-gatsby.png differ diff --git a/docs/blog/2018-06-26-card-sort-results/contributing-dendogram.png b/docs/blog/2018-06-26-card-sort-results/contributing-dendogram.png new file mode 100644 index 0000000000000..5f1b2feddd620 Binary files /dev/null and b/docs/blog/2018-06-26-card-sort-results/contributing-dendogram.png differ diff --git a/docs/blog/2018-06-26-card-sort-results/deployment-categories.png b/docs/blog/2018-06-26-card-sort-results/deployment-categories.png new file mode 100644 index 0000000000000..22bbddc63ef95 Binary files /dev/null and b/docs/blog/2018-06-26-card-sort-results/deployment-categories.png differ diff --git a/docs/blog/2018-06-26-card-sort-results/index.md b/docs/blog/2018-06-26-card-sort-results/index.md new file mode 100644 index 0000000000000..af9e0c010e627 --- /dev/null +++ b/docs/blog/2018-06-26-card-sort-results/index.md @@ -0,0 +1,107 @@ +--- +title: Presenting the Docs Redesign Card Sort Results +date: 2018-06-26 +author: Shannon Soper +tags: ["documentation"] +--- + +## What is a card sort? + +Recently, 36 Gatsby users completed an open card sort to help make our docs here on gatsbyjs.org easier to use. Without any outside input or help, they each sorted 90 cards into categories that made sense to them and then named those categories. + +### Raw & beautified data + +I ran this card sort through [OptimalSort](https://www.optimalworkshop.com/), a software that moderates the card sort and presents the data in usable forms. If you’re curious to see the full results, you can [view the data](https://www.optimalworkshop.com/optimalsort/x87kpp82/5x34psa3-0/shared-results/fa8b66knb66qyhwh5l8j38bd273vkkm7), including raw data as well as things like a similarity matrix and a [dendogram](https://support.optimalworkshop.com/hc/en-us/articles/201997650-Interpreting-the-OptimalSort-dendrograms). + +## How did participants categorize the docs? + +People sorted the docs into the following categories: +* Get Started / Welcome to Gatsby / Intro +* Development environment +* Releases & Migration +* Core Concepts / About Gatsby +* Advanced Guides +* API Reference +* Tutorials / Examples +* Contributing + +These categories weren’t too surprising (I included multiple names when the some category names were equally popular). However, upon further digging into the data, I discovered some unexpected results that further refine how we might categorize the docs, write new docs, and change how we think and talk about Gatsby. + +## PWA + +No one seems to know what to do with the doc titled “Building apps with Gatsby”. In the similarity matrix data visualization, 41% of people associated it with the “Authentication tutorial” doc and 41% also associated it with the “Progressive web app” doc. A 41% isn’t *very* strong. Essentially, this means participants didn’t think it “fit” very snugly alongside any other docs. + +![Building apps with Gatsby is weakly associated with other docs](building-apps-with-gatsby.png) + +This could mean several things: +1. We don’t have very many docs about how Gatsby can be used to build dynamic apps +2. People don’t think of Gatsby as a tool they’d use to build apps with +3. The title of the doc is too broad or too vague + +Without interviewing each participant I can’t be sure, but I’m inclined to think a combination of all three factors means people don’t know where to put that doc in the navigation. This might mean we need clarity in how we present what Gatsby *is* in all our informational material and marketing and that we build more docs about Gatsby being more than a static site generator. + +### Deployment + +There was a lot of disagreement about where docs about deployment should go. For example, card sort participants placed the “Build and deploy a live site” doc in 28 unique categories. Here’s a sample of the categories: + +![Deployment categories](deployment-categories.png) + +The three most common categories it was placed under are “Getting Started”, “Tutorials,” and “Deployment.” Other categories include “Examples,” “Guides,” and “Production.” Here are the deployment docs that need to find a place to call home: +* Build and deploy a site +* Preparing site for deployment +* Deploying a site live online + +One solution that occurred to me is to bring Deployment & Hosting to top level navigation as their own category, since there was so little agreement on where to put them. + +> ***NOTE:*** If you look at the data, the number of unique categorizations isn’t always a useful number, because Optimal Sort considers “getting started” and “get started” to be different categories even though a human eye can see they are essentially the same. However, in the case of these deployment docs, there were 28 categories and many of them are *truly unique*. + +### Core Concepts vs. Advanced Guides + +There was quite a bit of overlap in the docs people assigned to these two categories. This is probably because the two categories have a close relationship with each other; they work in harmony to help Gatsby users build at an advanced level. For example, if you read about how Gatsby works with GraphQL in “Core Concepts,” there is a high chance you’ll want to start playing with GraphQL queries and find examples of these in “Advanced Guides.” I’m not entirely sure how to reflect this close relationship in the docs; the most straightforward way is probably for each doc in “Core Concepts” to have a list of relevant links in "Advanced Guides," and vice versa. + +Here’s a sampling of docs that people associate with both categories: +* Search engine optimization (SEO) +* Authentication +* E-commerce + +List of other lonely docs that didn’t find a solid home through the card sort: +* The “RFC Process” doc didn’t find a snug fit. Two people didn’t know what it meant, and 44% of people put it under Contributing, but that’s not a majority. Seems like many people don’t know where to put it. I’m wondering if the title is too vague. +* There was little agreement on where the “Html.js” doc goes. There was a 47% association with Babel and a 47% association with using layouts to build reusable site sections. +* “React components” highest association was a 47% association with “basic structure of a Gatsby site” and all its associated pages. This slightly low association score probably results from the fact that the .org site doesn’t teach that much React at all, and there aren’t many docs on React specifically. + +## Dendogram adventures + +These screenshots that show a portion of the dendogram show that the clearest category was "Contributing", clear because the category name and the contents of the category are consistent: + +![Contributing dendogram](contributing-dendogram.png) + +Gatsby users are in agreement on what that category ought to be called and what docs it should contain :) + +## Next steps + +### Usability testing + +The next step is to conduct usability testing on a new design of the .org site. I’ve already conducted 8 usability tests with several more coming (5-7 produces reliable data in conventional UX research practices) and I’m seeing more ways to improve what we place in these categories as well as many ways I can improve my usability testing :). + +Many thanks to all those participants who have been enthusiastic and willing to give feedback, including Korey Boone, Shannon Smith, Peter Wiebe, Abhishek Vishwakarma, Ria Carmin, and Hugo Marques, Bogdan Lazar, Cameron Steele, and Simon Koelewijn. There are quite a few more people meeting with me in the upcoming week. + +These are the docs categories I’ve used for usability testing so far: +* Get Started +* Core Concepts +* Releases +* API Reference +* Recipes +* Tutorials +* Contributing + +Here are a few realizations from usability testing already: +* sometimes people don’t see the search bar on the .org site +* when searching for something in the docs or to solve an error, many people do a google search before using docs navigation or the .org search bar +* the category name “Recipes” was unclear to most people, although once they see the contents of the category, most people tend to like it +* the usability testing validated one of the card sort results, which is that some docs kind of fit in three categories: "Core Concepts" and "Recipes" and "Tutorials". These categories are all closely related and will need to link to each other often + +### What’s next + +Stay tuned for the results of the usability test and the new sidebar menu of the .org site, which will likely get released together :D + +And please read and comment on the [Doc Redesign RFC](https://github.com/gatsbyjs/rfcs/pull/5) if you have more ideas on how we can redesign the docs! diff --git a/docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md b/docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md index 4e2d436727ba8..9538fa621005c 100644 --- a/docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md +++ b/docs/blog/2018-2-27-why-i-upgraded-my-website-to-gatsbyjs-from-jekyll/index.md @@ -28,11 +28,11 @@ When delivering content to users on mobile devices, it is important to optimize However, it would be a pain to have to manually convert images into different sized thumbnails for a post. I wanted an automated image processing pipeline to automatically resize the images extracted from the markdown documents, and then automatically populate the `srcset` attribute on the images in the output HTML document. I found the [Jekyll Responsive Image Plugin](https://github.com/wildlyinaccurate/jekyll-responsive-image) great for this. It allows me to create templates which will be used by Jekyll when rendering the markdown and automatically does the image resizing. -Even so, when I tried to do more complicated workflows like adding CSS preprocessing with dependence on the JavaScript ecosystem with the [Node Package Manager (npm)](https://www.npmjs.com/), it became a lot more convoluted. Looking at a few recipes I’ve found, I would have to dive down the road of writing [Gulp](https://gulpjs.com/) workflows and somehow connect them to Jekyll commands. I also chanced upon the [Jekyll Asset Pipeline](https://github.com/matthodan/jekyll-asset-pipeline) which seems what I could use. I didn’t dive too deep into it, but from brief glances it seems like I would have to come up with a lot of custom scripting to interface with Javascript libraries on my own. +Even so, when I tried to do more complicated workflows like adding CSS preprocessing with dependence on the JavaScript ecosystem with the [Node Package Manager (npm)](https://www.npmjs.com/), it became a lot more convoluted. Looking at a few recipes I’ve found, I would have to dive down the road of writing [Gulp](https://gulpjs.com/) workflows and somehow connect them to Jekyll commands. I also chanced upon the [Jekyll Asset Pipeline](https://github.com/matthodan/jekyll-asset-pipeline) which seems what I could use. I didn’t dive too deep into it, but from brief glances it seems like I would have to come up with a lot of custom scripting to interface with JavaScript libraries on my own. -I guess having used [webpack](https://webpack.js.org/) at work, I was pampered by this open source community where there are loaders and documented recipes for doing almost anything, granted that someone was willing to wade into the world of "Javascript fatigue". Around the same time, [@yangshun](https://github.com/yangshun) introduced me to [Gatsby](https://www.gatsbyjs.org/), a React static site generator which seemed really fascinating. It also seemed a good opportunity for me to get my hands dirty with frontend development again. +I guess having used [webpack](https://webpack.js.org/) at work, I was pampered by this open source community where there are loaders and documented recipes for doing almost anything, granted that someone was willing to wade into the world of "JavaScript fatigue". Around the same time, [@yangshun](https://github.com/yangshun) introduced me to [Gatsby](https://www.gatsbyjs.org/), a React static site generator which seemed really fascinating. It also seemed a good opportunity for me to get my hands dirty with frontend development again. -As I had some free time on my hands, why not rewrite everything again and keep myself updated with the ever-changing Javascript ecosystem? Seems like a lot of fun! +As I had some free time on my hands, why not rewrite everything again and keep myself updated with the ever-changing JavaScript ecosystem? Seems like a lot of fun! ## Final Form — Gatsby @@ -85,9 +85,9 @@ export const pageQuery = graphql` When the `` component needs to be rendered into a page, the accompanying exported `pageQuery`, a GraphQL query is made, and the results are passed in as props into the component. -The real magic happens when the website is compiled into a production bundle. Running `gatsby build` will tell Gatsby to perform all the GraphQL queries defined and render all the React components into a HTML document, using a technique known as server-side rendering. This means that everything “React” is serialized and compiled to static HTML, ready to be viewed without Javascript. Visitors to the site will then be able to quickly load and interact with the static version of the page. +The real magic happens when the website is compiled into a production bundle. Running `gatsby build` will tell Gatsby to perform all the GraphQL queries defined and render all the React components into a HTML document, using a technique known as server-side rendering. This means that everything “React” is serialized and compiled to static HTML, ready to be viewed without JavaScript. Visitors to the site will then be able to quickly load and interact with the static version of the page. -Not only that, within the HTML document, there are instructions to load the Javascript bundle of your application asynchronously. When it has been loaded, the content displayed in the browser will be dynamically replaced by the React application, gaining interactivity. This also happens with the other pages of your site — Gatsby will ensure that they are asynchronously loaded so that when you click on a link, the data is already cached on the browser for React to swap out the DOM elements that need to be changed. Everything is done to give the illusion of speed to the viewer while asynchronously loading everything in the background. +Not only that, within the HTML document, there are instructions to load the JavaScript bundle of your application asynchronously. When it has been loaded, the content displayed in the browser will be dynamically replaced by the React application, gaining interactivity. This also happens with the other pages of your site — Gatsby will ensure that they are asynchronously loaded so that when you click on a link, the data is already cached on the browser for React to swap out the DOM elements that need to be changed. Everything is done to give the illusion of speed to the viewer while asynchronously loading everything in the background. ### Plugins diff --git a/docs/blog/2018-2-6-choosing-a-back-end/index.md b/docs/blog/2018-2-6-choosing-a-back-end/index.md index abfd3628d5837..0a175436a13ad 100644 --- a/docs/blog/2018-2-6-choosing-a-back-end/index.md +++ b/docs/blog/2018-2-6-choosing-a-back-end/index.md @@ -15,7 +15,7 @@ The only thing as abundant than Headless CMS options is Static Site Generator op Gatsby pitches as a “Blazing-fast static site generator for React”. So if I can build sites, but also encompass some React knowledge, all the better right? And I’m always looking for side-projects and sites for others, so if I can get a JAMstack sorted quicker and easier than my previous WordPress stack, then all the better going forward! I thought it was best to start with my own site, to test the viability. -> **What-stack?** JAM stands for Javascript, API, Markup. There are lots of benefits to this type of site, but the one I’m interested in is that your CMS is detached from your site - no hefty WordPress build for your tiny blog site. +> **What-stack?** JAM stands for JavaScript, API, Markup. There are lots of benefits to this type of site, but the one I’m interested in is that your CMS is detached from your site - no hefty WordPress build for your tiny blog site. > [You can read more on the JAMstack website](https://jamstack.org/). I found Gatsby a real pleasure. You can find tutorials on their site for setup and once you see the code it’s fairly simple. I can personally recommend [Scott Tolinski’s series - available on Youtube](https://www.youtube.com/watch?v=b2H7fWhQcdE&list=PLLnpHn493BHHfoINKLELxDch3uJlSapxg). Gatsby nicely wraps up React and React Router with a nice folder structure, webkit, ES6, SASS support and - importantly - GraphQL. diff --git a/docs/docs/gatsby-on-windows.md b/docs/docs/gatsby-on-windows.md index 5aa8d3fa5358b..a389173eaa68b 100644 --- a/docs/docs/gatsby-on-windows.md +++ b/docs/docs/gatsby-on-windows.md @@ -59,3 +59,6 @@ further instructions and contact the `node-gyp`team on Note 1 : the Visual Studio Community 2017 surely contains the package too but we weren't able to find it. If you found it, run `npm config set msvs_version 2017` instead and report it here with a screenshot! + +## gatsby-plugin-sharp requires Node x64 +Some plugins which depend on native NPM dependencies require the Node x64 build of Node.js. If you're struggling to install gatsby-plugin-sharp, try installing Node x64 and removing `node_modules` and running `npm install`. diff --git a/docs/docs/gatsby-starters.md b/docs/docs/gatsby-starters.md index 7f6a8b9f3cc78..385094f338fe2 100644 --- a/docs/docs/gatsby-starters.md +++ b/docs/docs/gatsby-starters.md @@ -799,3 +799,16 @@ gatsby new my-blog https://github.com/gatsbyjs/gatsby-starter-blog#v2 - Based on [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default) - Using [Tachyons](https://github.com/tachyons-css/tachyons/) for CSS. [Read the tachyons docs](http://tachyons.io/docs/) - Find out about the tachyons open source component library [here](http://tachyons.io/components/) to get you going. + +- 💀[gatsby-starter-skeleton](https://github.com/Undistraction/gatsby-starter-skeleton) ([Demo](https://undistraction.github.io/gatsby-starter-skeleton/)) + + Features: + + - Full-featured site for developer or small company + - Includes Articles and Projects + - Includes Tags and Categores + - Minimal but stylish default theme + - Styled Components and CSSAPI for styles + - Configure many of the site's features from a separate site config files + - Extended Markdown support, responsive embeds, solid inline code support and lots of other goodness + - Well commented and documented diff --git a/docs/docs/graphql-reference.md b/docs/docs/graphql-reference.md index ee5d61bf3a470..73825391b47b5 100644 --- a/docs/docs/graphql-reference.md +++ b/docs/docs/graphql-reference.md @@ -76,6 +76,14 @@ To add variables to page component queries, pass these in the `context` object [ +## Group + +You can also group values on the basis of a field e.g. the title, date or category and get the field value, the total number of occurences and edges. + +The query below gets us all authors (`fieldValue`) who wrote a blogpost and how many blogposts (`totalCount`) they wrote. In addition we're grabbing the `title` and `slug` of the author's articles. + + + ## Where next? Try [running your own queries](), check out the rest of [the docs](/docs/) or run through [the tutorial](/tutorial/). diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 921e5d825fa22..f68ee6b790bd9 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -58,12 +58,13 @@ Read on for a detailed guide on what's new in version 2! - [Only allow defined keys on node.internal object](#only-allow-defined-keys-on-the-node-internal-object) - [Import `graphql` types from `gatsby/graphql`](#import-graphql-types-from-gatsbygraphql) - [Move Babel Configuration`](#move-babel-configuration) +- [Plugin specific changes](#plugin-specific-changes) You can start with a few of the most important steps - install Gatsby v2 dependencies and update your layout components. ## Update Gatsby version -Update your `package.json` to use the pre-release versions of Gatsby and any related packages. +Update your `package.json` to use the pre-release versions of Gatsby. `package.json` @@ -77,6 +78,20 @@ Update your `package.json` to use the pre-release versions of Gatsby and any rel > Note: Gatsby v2 is in pre-release so you may encounter further breaking changes. +## Update Gatsby related packages + +Update your `package.json` to use the pre-release versions of Gatsby related packages. Any package name that starts with `gatsby-` should be upgraded to use the `next` version. Note, this only applies to plugins managed in the gatsbyjs/gatsby repo. If you're using community plugins, they might not be upgraded yet. Check their repo for the status. Many plugins won't actually need upgraded so they very well might keep working. For example: + +`package.json` + +```json +"dependencies": { + "gatsby-plugin-google-analytics": "next", + "gatsby-plugin-netlify": "next", + "gatsby-plugin-sass": "next", +} +``` + ## Manually install React In v1, the `react` and `react-dom` packages were included as part of the `gatsby` package. They are now `peerDependencies` so you are required to install them into your project. @@ -503,3 +518,19 @@ The latest version of Gatsby uses Babel 7, which introduced [a new behavior for [This GitHub comment](https://github.com/facebook/jest/issues/1468#issuecomment-361260279) documents the steps needed to do that. More information on Gatsby and Babel configuration available [here](/docs/babel/#how-to-use-a-custom-babelrc-file). + +## Plugin specific changes + +Some plugins require additional changes before your site will compile. +For example, if you use [`gatsby-plugin-typography`](https://www.gatsbyjs.org/packages/gatsby-plugin-typography/), you now need to explicitly export `scale` and `rhythm` as named exports from your typography config module. + +`src/utils/typography.js` + +```diff +- const typography = new Typography(); +- export default typography; + ++ const typography = new Typography(); ++ const { rhythm, scale } = typography; ++ export { rhythm, scale, typography as default }; +``` diff --git a/docs/docs/node-interface.md b/docs/docs/node-interface.md index 621668966df86..04276e2f635d9 100644 --- a/docs/docs/node-interface.md +++ b/docs/docs/node-interface.md @@ -16,7 +16,7 @@ fields: Object, internal: { contentDigest: String, // Optional media type (https://en.wikipedia.org/wiki/Media_type) to indicate - // to transformer plugins this node has data they can futher process. + // to transformer plugins this node has data they can further process. mediaType: String, // A globally unique node type chosen by the plugin owner. type: String, diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index 6b5bf70920747..6df9876d5bbd0 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -65,3 +65,12 @@ Like all `gatsby-*` files, the code is not processed by Babel. If you want to use JavaScript syntax which isn't supported by your version of Node.js, you can place the files in a `src` subfolder and build them to the plugin folder root. + +## What don't you need plugins for? + +Most third-party functionality you want to add to your website will follow standard Javascript and React.js patterns for importing packages and composing UIs. These do not require a Gatsby plugin! + +Some examples: +* Importing Javascript packages that provide general functionality, such as `lodash` or `axios` +* Using React components or component libraries you want to include in your UI, such as `Ant Design`, `Material UI`, or the typeahead from your component library. +* Integrating visualization libraries, such as `Highcharts` or `d3`. diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index b0bac2c2eb9e7..88d4d6d726c40 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -12,11 +12,13 @@ into site-specific plugins. Gatsby has a large and growing set of plugins. To search/browse official and community plugins and their documentation, visit the [Plugin Library](/packages/). -For information on building your own plugin, see the [Plugin Authoring page](/docs/plugin-authoring/). +For documentation on the different types of plugins and the functionality provided by each, see the [Plugin Authoring page](/docs/plugin-authoring/). + +For a walkthrough of how to build and publish your own plugin, see the [Source Plugin Tutorial](/docs/source-plugin-tutorial/) ## How to use Gatsby plugins? -Gatsby plugins are just Node.js packages meaning you install them like anything else in +Gatsby plugins are Node.js packages, so you can install them like other packages in node using NPM. For example, `gatsby-transformer-json` is a package which adds support for JSON diff --git a/docs/docs/querying-with-graphql.md b/docs/docs/querying-with-graphql.md index 47574416a44d1..6cfbee34f87bf 100644 --- a/docs/docs/querying-with-graphql.md +++ b/docs/docs/querying-with-graphql.md @@ -208,7 +208,7 @@ See also the following blog posts: Notice that in the above example for [querying images](#images), we used `...GatsbyImageSharpFixed`, which is a GraphQL Fragment, a reusable set of fields for query composition. You can read more about them [here](http://graphql.org/learn/queries/#fragments). -If you wish to define your own fragments for use in your application, you can use named exports to export them in any Javascript file, and they will be automatically processed by Gatsby for use in your GraphQL queries. +If you wish to define your own fragments for use in your application, you can use named exports to export them in any JavaScript file, and they will be automatically processed by Gatsby for use in your GraphQL queries. For example if I put a fragment in a helper component, I can use that fragment in any other query: diff --git a/docs/features/gatsby-specs.csv b/docs/features/gatsby-specs.csv index 5c5a19258a9a8..a15b8cca79bc6 100644 --- a/docs/features/gatsby-specs.csv +++ b/docs/features/gatsby-specs.csv @@ -56,7 +56,7 @@ Developer Experience,Maintenance & Extensibility,Serverless,3,3,2,2,"

Serverle

Gatsby provides asset pipelining out of the box through its build system on top of Webpack and Babel. Wordpress and Jekyll don't provide this, although you could set up your own. Squarespace has a limited and tightly controlled development environment (no local development) that doesn't allow for creating an asset pipeline.

" ,,CSS Extensions (eg Sass),3,3,1,1,"Languages such as Sass and Less compile to CSS while offering support for variables, functions, hierarchal class definitions; libraries like glamor and aphrodite allow css to be colocated with JS and HTML in React. This solves problems in vanilla CSS like global namespacing, non-determinatism, dead code elimination and minification" -,,Advanced Javascript syntax,3,1,1,0,"Javascript has become more powerful as a language in the last several years, making it easier to write code. These include: +,,Advanced JavaScript syntax,3,1,1,0,"JavaScript has become more powerful as a language in the last several years, making it easier to write code. These include: