diff --git a/.eslintrc b/.eslintrc.json similarity index 97% rename from .eslintrc rename to .eslintrc.json index 424a3154912a4..a049b127e7747 100644 --- a/.eslintrc +++ b/.eslintrc.json @@ -62,7 +62,7 @@ { "files": [ "packages/**/gatsby-browser.js", - "pacakges/gatsby/cache-dir/**/*" + "packages/gatsby/cache-dir/**/*" ], "env": { "browser": true diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index c7bb401a5c022..0000000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,45 +0,0 @@ - - -## Description - -Describe the issue or the enhancement that you want to see. - -### Steps to reproduce - -Clear steps describing how to reproduce the issue. - -### Expected result - -What should happen? - -### Actual result - -What happened. - -### Environment - -* Gatsby version (`npm list gatsby`): -* gatsby-cli version (`gatsby --version`): -* Node.js version: -* Operating System: - -### File contents (if changed): - -`gatsby-config.js`: -`package.json`: -`gatsby-node.js`: -`gatsby-browser.js`: -`gatsby-ssr.js`: diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000000..ae7c18037e272 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: Bug Report 🐞 +about: Something isn't working as expected? Here is the right place to report. +--- + + + +## Description + +Describe the issue that you're seeing. + +### Steps to reproduce + +Clear steps describing how to reproduce the issue. + +### Expected result + +What should happen? + +### Actual result + +What happened. + +### Environment +* Gatsby version (`npm list gatsby`): +* gatsby-cli version (`gatsby --version`): +* Node.js version: +* Operating System: + +### File contents (if changed) +`gatsby-config.js`: N/A +`package.json`: N/A +`gatsby-node.js`: N/A +`gatsby-browser.js`: N/A +`gatsby-ssr.js`: N/A diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000000000..ed10d0c52068d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,27 @@ +--- +name: Feature Request 💡 +about: Suggest a new idea for the project. +--- + + + +## Summary + +Brief explanation of the feature. + +### Basic example + +If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable. + +### Motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000000000..811ca5adc840b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,19 @@ +--- +name: Question 🤔 +about: Usage question or discussion about Gatsby. +--- + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce1f6fb68ed36..d85cfe424befe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,157 +1,3 @@ ---- -title: How to Contribute ---- +## How to Contribute -## Contributing - -We want contributing to Gatsby to be fun, enjoyable, and educational for anyone and everyone. Contributions go far beyond pull requests and commits; we are thrilled to receive a variety of other contributions including the following: - -* Blogging, speaking about, or creating tutorials about one of Gatsby's many features. Mention @gatsbyjs on Twitter and/or email shannon [at] gatsbyjs [dot] com so we can give pointers and tips (if you want them :) and help you spread the word. Please add your blog posts and videos of talks to our [Awesome Gatsby](/docs/awesome-gatsby/) page. -* [Submit new feature ideas through an RFC](/blog/2018-04-06-introducing-gatsby-rfc-process/) -* Submitting new documentation; titles in _italics_ on gatsbyjs.org are stubs and need contributions -* Tweeting about things you build with @gatsbyjs (make sure to @ mention us!) -* Submitting documentation updates, enhancements, designs, or bugfixes -* Submitting spelling or grammar fixes -* Adding unit or functional tests -* Triaging [GitHub issues](https://github.com/gatsbyjs/gatsby/issues) -- especially determining whether an issue still persists or is reproducible -* [Reporting bugs or issues](/docs/how-to-file-an-issue/) -* Searching for Gatsby on Discord or Spectrum and helping someone else who needs help -* Teaching others how to contribute to Gatsby's repo! - -If you are worried or don't know where to start, you can always reach out to Shannon Soper(@shannonb_ux) on Twitter or simply submit an issue and a maintainer can help give you guidance! - -Looking to speak about Gatsby? We'd love to review your talk abstract/CFP! You can email it to shannon [at] gatsbyjs [dot] com, and we can give pointers or tips!!! - -### Creating your own plugins and loaders - -If you create a loader or plugin, we would <3 for you to open source it and put it on npm. For more information on creating custom plugins, please see the documentation for [plugins](/docs/plugins/) and the [API specification](/docs/api-specification/). - -### Contributing to the repo - -Gatsby uses a "monorepo" pattern to manage its many dependencies and relies on -lerna and yarn to configure the repository for active development. - -You can install the latest version of Gatsby by following these steps: - -* Clone the repo, navigate to its directory. -* ensure you have the latest version of yarn installed (>= 1.0.2) - https://yarnpkg.com/en/docs/install -* Install dependencies using `yarn run bootstrap` in the root of the repo. - -The usual contributing steps are: - -* Fork the [official repository](https://github.com/gatsbyjs/gatsby). -* Clone your fork: git clone `git@github.com:/gatsby.git` -* Setup up repo and install dependencies: `yarn run bootstrap` -* Make sure tests are passing for you: `yarn test` -* Create a topic branch: `git checkout -b topics/new-feature-name` -* Run `yarn run watch` from the root of the repo to watch for changes to packages' source code and compile these changes on-the-fly as you work. Note that the watch command can be resource intensive. To limit it to the packages you're working on, add a scope flag, like `yarn run watch --scope={gatsby,gatsby-cli}`. To watch just one package, run `yarn run watch --scope=gatsby`. -* Install [gatsby-dev-cli](/packages/gatsby-dev-cli/) globally: `yarn global add gatsby-dev-cli` -* Run `yarn install` in each of the sites you're testing. -* For each of your Gatsby test sites, run the `gatsby-dev` command there to copy - the built files from your cloned copy of Gatsby. It'll watch for your changes - to Gatsby packages and copy them into the site. For more detailed instructions - see the [gatsby-dev-cli README](/packages/gatsby-dev-cli/) -* Add tests and code for your changes. -* Once you're done, make sure all tests still pass: `yarn test` -* Commit with a ["Signed-off-by"](#developer-certificate-of-origin) line appended - to your commit message and push to your fork. -* Create a pull request from your branch. - -### Contributing to the documentation. - -Gatsby, unsurprisingly, uses Gatsby for its documentation website. - -If you want to add/modify any Gatsby documentation, go to the -[docs folder on GitHub](https://github.com/gatsbyjs/gatsby/tree/master/docs) and -use the file editor to edit and then preview your changes. GitHub then allows -you to commit the change and raise a PR right in the UI. This is the _easiest_ -way you can contribute to the project! - -However, if you want to make more changes to the website, that is, change -layouts, add sections/pages, follow the steps below. You can then spin up your -own instance of the Gatsby website and make/preview your changes before raising -a pull request. - -* Clone the repo and navigate to `/www` -* Run `yarn` to install all of the website's dependencies. -* Run `gatsby develop` to preview the website in `http://localhost:8000` -* The Markdown files for the documentation live in `/docs` folder. Make - additions or modifications here. -* Make sure to double check your grammar and capitalise correctly. -* Commit with a ["Signed-off-by"](#developer-certificate-of-origin) line appended - to your commit message and push to your fork. -* Create a pull request from your branch. - -### Developer Certificate of Origin - -The Gatsby repository enforces the -[Developer Certificate of Origin](https://developercertificate.org/) (DCO) on -Pull Requests. It requires all commit messages to contain the `Signed-off-by` -line with an email address that matches the commit author. - -Git has a `-s` (or longer `--signoff`) command line option to append this -automatically to your commit message: - -```shell -$ git commit -s -m 'This is my commit message' -``` - -If you've already created a Pull Request and notice that the DCO check is failing, you -can use this command to append a signoff message to your commits: - -```shell -$ git rebase --signoff -``` - -or amend your last commit if you have a single commit in your Pull Request: - -```shell -$ git commit --amend -s -``` - -## Development tools - -### Redux devtools - -Gatsby uses Redux for managing state during development and building. It's often -helpful to see the flow of actions and built-up state for a site you're working -on or if adding new functionality to core. We leverage -[Remote Redux Devtools](https://github.com/zalmoxisus/remote-redux-devtools) and -[RemoteDev Server](https://github.com/zalmoxisus/remotedev-server) to give you use the Redux -devtools extension for debugging Gatsby. - -To use this, first install -[redux-devtools-extension](https://github.com/zalmoxisus/redux-devtools-extension) -in your browser. Then in your Gatsby repo, run `npm run remotedev`. Then in your -site directory run `REDUX_DEVTOOLS=true gatsby develop`. Depending on your -operating system and shell, you may need to modify how you set the -`REDUX_DEVTOOLS` environment variable. - -At this point, your site will be sending Redux actions and state to the remote -server. - -To connect to this, you need to setup the devtools extension to talk to the -remote server. - -First open the remote devtools. - -![how to open the redux remote devtools extension](./images/open-remote-dev-tools.png) - -Then click settings along the bottom menu and set the host and port. - -![how to set the host/port for the remote devtools extension to connect to Gatsby](./images/remote-dev-settings.png) - -After this, the devtools extension _should_ connect to the remote server and -you'll see actions start showing up. - -![gatsby redux remote devtools](./images/running-redux-devtools.png) - -**Warning!! Lots of buginess**. While having this available is extremely -helpful, this setup is very buggy and fragile. There is a memory leak in the -extension that's triggered it seems every time you restart the Gatsby -development server. Also the extension often, for no apparent reason, just won't -show any actions from the remote server. It'll also often freeze up. The best -solution seems to just be turning everything off and on again. Fixing up these -tools would be very helpful for us and many others using these tools if someone -wants to take this on! +For information related to contributing to Gatsby, please check out the [How to Contribute](https://www.gatsbyjs.org/docs/how-to-contribute/) section of the documentation at the Gatsby site. diff --git a/README.md b/README.md index eda08eda9970b..1a991af3df76b 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ Websites built with Gatsby: * [The freeCodeCamp Guide](https://guide.freecodecamp.org) ([source](https://github.com/freeCodeCamp/guides)) * [Storybook](https://storybook.js.org) ([source](https://github.com/storybooks/storybook)) +* [Learn Storybook](https://learnstorybook.com) ([source](https://github.com/hichroma/learnstorybook.com)) * [FloydHub's Blog](https://blog.floydhub.com) * [mParticle's Documentation](https://docs.mparticle.com) * [Segment's Blog](https://segment.com/blog/) @@ -164,7 +165,7 @@ Websites built with Gatsby: * [Portfolio / Blog of Preston Richey](https://prestonrichey.com/) ([source](https://github.com/prichey/prestonrichey.com)) * [Beach Hut Poole](https://www.beachhutpoole.co.uk/) * [In Sowerby Bridge](https://www.insowerbybridge.co.uk/) -* [枫上雾棋的日志](https://fengshangwuqi.github.io/fswq-blog/) +* [枫上雾棋的日志](https://fengshangwuqi.github.io/) * [Juliette Pretot's Portfolio](https://juliette.sh) * [Théâtres Parisiens](http://theatres-parisiens.fr/) ([source](https://github.com/phacks/theatres-parisiens)) * [Jia Hao's Website / Blog](https://jiahao.codes/) ([source](https://github.com/jiahaog/jiahao.codes)) @@ -194,8 +195,6 @@ Websites built with Gatsby: * [WebGazer](https://www.webgazer.io) * [Joe Seifi's Blog](http://seifi.org) * [Bartosz Dominiak Blog/Portfolio](http://www.bartoszdominiak.com/) ([source](https://github.com/bartdominiak/blog)) -* [HBTU MUN 2018](https://hbtumun18.netlify.com/) - ([source](https://github.com/HaoZeke/hbtuMun18)) * [The Audacious Project](https://audaciousproject.org/) * [upGizmo](https://www.upgizmo.com/) * [The Bastion Bot](https://bastionbot.org/ "The Bastion Bot") @@ -204,6 +203,18 @@ Websites built with Gatsby: * [F1 Vision](https://f1vision.com/) * [GraphQL College](https://graphql.college) ([source](https://github.com/GraphQLCollege/graphql-college)) * [Hyunwoo Kim - Blog/Portfolio](https://devhalloween.com) ([source](https://github.com/khw1031/dev-blog)) +* [Abinav Seelan - Personal Website](https://abinavseelan.com) ([source](https://github.com/abinavseelan/abinavseelan.com)) +* [Dovetail](https://dovetailapp.com) +* [Bart van der Waerden Blog](http://bartvanderwaerden.com/) ([source](https://github.com/BartvdWaerden/BartvdWaerden.github.io)) +* [Canella Riccardo - Portfolio](https://canellariccardo.it) ([source](https://github.com/thecreazy/canellariccardo.it)) +* [Eviction Free NYC!](https://www.evictionfreenyc.org/) ([source](https://github.com/JustFixNYC/eviction-free-nyc)) +* [Rafael Belliard's Portfolio](https://rafael.do) ([source](https://github.com/rebelliard/rebelliard.github.io)) +* [Tinder Interracial Couple Emoji Project](https://emoji.tinder.com/) +* [aQuICK](https://aquick.review/) + ([source](https://github.com/aQuICK-Review/aQuick)) +* [Workshop In The Woods](https://www.workshop-in-the-woods.com/) ([source](https://github.com/ryanwiemer/workshop)) +* [Steven Koerts - Portfolio](http://stevenkoerts.nl/)([source](https://github.com/Steven24K/Steven24K.github.io)) +* [Ray Gesualdo - Personal Website](http://www.raygesualdo.com/) ([source](https://github.com/raygesualdo/raygesualdo.com)) ## Docs diff --git a/docs/blog/2018-03-07-why-we-created-the-plugin-library/index.md b/docs/blog/2018-03-07-why-we-created-the-plugin-library/index.md index c2f55fe92ca96..911888048b3e2 100644 --- a/docs/blog/2018-03-07-why-we-created-the-plugin-library/index.md +++ b/docs/blog/2018-03-07-why-we-created-the-plugin-library/index.md @@ -15,7 +15,7 @@ From October 2017 to February 2018, I conducted over 60 interviews with Gatsby u ## Jobs to be done -After compiling data from the interviews, I drew what’s called an “empathy map” to put myself in the shoes of Gatsby users. This map describes what a Gatsby users usually experienced when searching for plugins. +After compiling data from the interviews, I drew what’s called an “empathy map” to put myself in the shoes of Gatsby users. This map describes what Gatsby users usually experienced when searching for plugins. ![Empathy map](empathy-map.png) diff --git a/docs/blog/2018-04-25-how-gatsby-changes-teams-website-development-workflow/index.md b/docs/blog/2018-04-25-how-gatsby-changes-teams-website-development-workflow/index.md new file mode 100644 index 0000000000000..9c503aaa80aea --- /dev/null +++ b/docs/blog/2018-04-25-how-gatsby-changes-teams-website-development-workflow/index.md @@ -0,0 +1,64 @@ +--- +title: How Gatsby Changes Teams' Website Development Workflow +date: "2018-04-25" +author: "Sam Bhagwat" +excerpt: Gatsby is more than just a new website framework -- it changes the way your team works together. +tags: ["collaboration"] +--- + +Gatsby is more than just a new website framework -- creating websites in Gatsby is a fundamentally different paradigm than in a CMS-specific framework. + +Website teams adopting Gatsby report improved collaboration at each stage -- from architecture and user research, to design and development, to testing and launch. Many of these derive from Gatsby features: faster development cycles, easy compatibility with React component libraries, a CMS-agnostic development environment, the ability to easily deploy static build artifacts. + +To fully take advantage of new, Gatsby-enabled workflows, consider adopting some of these techniques: + +### Architecture + +_Take advantage of extended evaluation periods to build a component library_ + +Larger companies considering adopting Gatsby often plan in terms of migrating multiple sites (or internationalized versions of sites) over a timeframe of a few months to two years. These projects can have long preparation times before active development starts. + +One high-leverage activity during these time windows is to focus development on a React component library. Then, when development begins the team is able to quickly assemble Gatsby React pages from these pre-built components. Consider designating senior UI developers as "component architects" in this process. + +_Consider a less-expensive CMS or multi-modal architecture_ + +Choosing Gatsby frees your CMS from doing a lot of the heavy lifting, such as scaling to meet peak load and having a rich, modern web development experience. If you're using an expensive enterprise CMS, Gatsby can help your project stay within budget by allowing you to choose a simpler, cheaper option, such as a hosted Drupal instance, or a content management SaaS like Contentful. + +Another consideration is that not all of your content _has_ to live in one system. Often, you can save time and money by create a multi-modal content architecture with best-in-class solutions for each of the different workflows & capabilities you require. You might choose to manage your e-commerce product catalog in Shopify, company-specific marketing pages in Contentful, and form-based event data in Google Sheets & Forms. Gatsby offers plugins to pull data from multiple sources, while building with one stack. + +### User Research + +_Utilize developers to prototype faster_ + +In order to do user testing, usually user researchers work with designers to construct pixel perfect prototypes of various options, either static or clickable. Constructing and iterating on these artifacts can take days or weeks. + +Gatsby makes another option possible. Some Gatsby users report [setting up a production site](https://www.gatsbyjs.org/blog/2018-01-18-how-boston-gov-used-gatsby-to-be-selected-as-an-amazon-hq2-candidate-city/) with live UI that is building and deploying in under an hour. + +Especially if your organization already uses a React or HTML-based component library, your team may consider bringing in a developer to construct live wireframe-level prototypes. This may enable you to accelerate the user research process, start the development process with a working prototype rather than from scratch, and ultimately let you arrive at a better version of your site. + +### Development + +_Make progress without access to the client CMS_ + +Sometimes website development teams don't gain access to the client's CMS until development has already started. This can happen for a variety of reasons -- internal client policies, the need to onboard content editors, and so forth. Typically this is a difficult situation where development can be blocked or delayed, and can lead to timeline slippage, crunch time at the end of the project, and so on. + +With Gatsby, the CMS-agnostic development workflow gives teams tools to continue to make progress even without access to client content. One common approach is to develop and prototype UIs pulling placeholder content from markdown files stored in the repo. When the team gains access, it only takes a few lines of code to reconfigure the site to pull content from the CMS. + +## QA and Testing + +Gatsby's extensible system of API hooks, tight integration with static hosts like Netlify, and use of React's modular component architecture, allow website teams to enable more effective QA <-> Development workflows. + +_Use development pages to communicate project status & collaborate with designers_ + +One option some teams have found powerful is to create static page components within Gatsby to [handle necessary parts of the development/QA workflow](https://www.gatsbyjs.org/blog/2018-04-11-trying-out-gatsby-at-work-and-co/#1-pre-integration-qa). + +This could include: +* Checking UI implementation of various components to ensure behavior is intended +* Enabling QA visibility into desired site-specific page-level validations, such as "don't end a page in a carousel" +* Communicating build history and last build status + +_Use branch and pull request-based artifacts to collaborate on specific pieces of work_ + +Using the [branch and pull request-based artifacts](https://www.gatsbyjs.org/blog/2018-04-11-trying-out-gatsby-at-work-and-co/#building-staging-urls +) automatically created by a service like Netlify for collaboration between developers, designers, and QA. Because generated artifacts are static, pull request collaboration workflows are resilient to underlying content schema changes, such as field deletion, that might break a typical CMS development environment. + diff --git a/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/design-mapping.jpeg b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/design-mapping.jpeg new file mode 100644 index 0000000000000..0800157b47f0f Binary files /dev/null and b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/design-mapping.jpeg differ diff --git a/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/housing-court-example.png b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/housing-court-example.png new file mode 100644 index 0000000000000..6595ff48b07e0 Binary files /dev/null and b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/housing-court-example.png differ diff --git a/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/index.md b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/index.md new file mode 100644 index 0000000000000..f0407401f5987 --- /dev/null +++ b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/index.md @@ -0,0 +1,212 @@ +--- +title: Building Eviction Free NYC with GatsbyJS + Contentful +date: "2018-04-27" +author: "Dan Kass" +excerpt: Lessons in building a minimal, low-connectivity site for navigating a daunting legal process. +tags: ["i18n", "netlify", "case-studies", "contentful"] +canonicalLink: https://medium.com/@JustFixNYC/building-eviction-free-nyc-with-gatsbyjs-contentful-a0308bfcb866 +publishedAt: "JustFixNYC" +--- + +On March 29th, we launched [Eviction Free NYC](http://www.evictionfreenyc.org/) with the [Right to Counsel Coalition](https://www.righttocounselnyc.org/) as part of a campaign to educate tenants living in affordable housing on their legal rights and how to navigate the daunting process of receiving an eviction notice. + +In order to build this new resource we applied a [human-centered design process](https://medium.com/@JustFixNYC/co-designing-eviction-free-nyc-b54570c69153) followed by specialized technical scoping in order to determine what was best for our users and build something for this unique context. **That process led us to using GatsbyJS, Contentful, and Netlify!** Below, we've written up how we mapped design to dev, approached different stakeholders, and utilized Gatsby's great flexibility & plugin library. + + +#### **Mapping Design Considerations to Technical Scoping** + +![](design-mapping.jpeg) +*Journey mapping for a tenant organizing process!* + +We started this process with a pretty strong sense of our average user’s +technical capacity and degree of comfort in using a website or app. For the past +3 years, we’ve been collecting user insights from the [JustFix.nyc Tenant +Web-App](https://www.justfix.nyc/) and other resources. As you might imagine, +the majority of our users are coming from mobile devices (**over 95% of +low-income Americans now have a device that connects to the Internet**) and +usually do not have a very fast connection to the Internet. We learned from +user-testing in Housing Court that there is usually little-to-no cell +reception in the building. We also knew that internationalization (i18n) and +language localization would be a launch requirement. Previous analytics from the +Tenant Web-App also informed us to account for older browsers such as Internet +Explorer 11, given that many older users and nonprofit employees still use it. + +For coalition members, the site needed to be incredibly adaptable and easily +managed from a [Content Management +System](https://en.wikipedia.org/wiki/Content_management_system), or CMS. The +RTC policy and coverage areas change on an almost daily basis, and thus required +a content modelling system that would prevent the site from quickly becoming +outdated. We also wanted to utilize this system to make it easy for new +languages to be added and maintained with as little technical knowledge as +possible. + +#### **Our solution: GatsbyJS** + +We knew that we would build the site in [React](https://reactjs.org/). +Developers can build websites quickly and reliably through its modular +architecture and extensive system of third-party components. React’s simple +component-based philosophy creates code and structure that just *makes sense*, +allowing other developers to more easily contribute to the project as well. +It’s also unobtrusive enough that it can be applied to both large and small web +development projects. + +From there, we looked for different scaffolds that would help us get +up-and-running quickly. While we’re big fans of +[create-react-app](https://github.com/facebook/create-react-app) and have used +it on other projects, due to an aggressive project timeline, we needed something +that provided a more “out-of-the-box” solution. We wound up building the site in +GatsbyJS, which is a **React-based static site generator**. GatsbyJS is the +perfect fit for a number of reasons: + +1. [Static sites](https://en.wikipedia.org/wiki/Static_web_page) load content much +more quickly than dynamic web applications, which require multiple +back-and-forth calls to a server in order to display the final composited view +to the user. They are more easily adaptable for low connectivity / offline +functionality for this reason. This allows us to provide a faster and more +reliable experience for tenants utilizing the service. +1. GatsbyJS ships with an incredible amount of pre-handled optimization features, +from prefetching resources to progressive image loading to inlining code blocks +so they don’t need to be fetched via +[AJAX](https://en.wikipedia.org/wiki/Ajax_(programming)). There was no way we +could have achieved this level of optimization on our own in this timeframe. +1. A growing plugin library that allows for easy integrations that utilize Gatsby’s +GraphQL data query system. With these we could easily use things like +[gatsby-source-contentful](https://www.gatsbyjs.org/packages/gatsby-source-contentful/?=conten) +and [gatsby-plugin-i18n](https://github.com/angeloocana/gatsby-plugin-i18n). +1. A growing community of developers sharing resources and best practices. Credit +is due to [mccrodp](https://github.com/mccrodp) for setting up +[gatsby-starter-contentful-i18n](https://github.com/mccrodp/gatsby-starter-contentful-i18n), +a boilerplate that synced Contentful and i18n features together and allowed us +to hit the ground running. + +#### **Using Contentful** + +[Contentful](https://www.contentful.com/) is a “headless” [Content Management +System](https://en.wikipedia.org/wiki/Content_management_system), or CMS. +Traditional CMS platforms, like Wordpress or Drupal, allow authors and editors +to easily create websites and publish content such as text articles, image, or +video embeds. A headless CMS takes those publishing features (and the easy admin +tools that come with them) and additionally gives you total flexibility as to +how the website itself is constructed. + +In previous projects where we used Contentful, content was loaded dynamically +(via AJAX) when a user visits the site. GatsbyJS instead pulls content from +Contentful *as the site compiles* (pre-deploy), not when the user visits it. +This change creates significantly less server requests after page load and +further speeds up the site’s final load time. + +With Contentful, you define *Content Models* in tandem with coding individual +pages in order to construct the structure of the site and its content. For +Eviction Free NYC, some sample *Content Models* are **Providers**, **Housing +Court Action Steps**, and meta-level page models, such as **LandingPage**. + +![](provider-example.png) +*An example of the Provider content model* + +As GatsbyJS compiles the site (either in dev or building for production), it +will pull content from Contentful and make it available via GraphQL. A file’s +GraphQL `pageQuery` will then populate your React component’s `props` with the +corresponding data, creating an incredibly simple pipeline from content → code. +As an example, here’s the provider portion of a sample `pageQuery`: + + providers { + title + acceptsRtcCases + phoneNumber + website + hours + intakeInstructions + address + logo { + resolutions(width: 100, height: 100) { + aspectRatio + width + height + src + srcSet + } + } + } + +#### **Challenge: Hyper-personalized result pages in a static site** + +When a tenant goes to Eviction Free NYC, they answer a simple questionnaire that +determines a results page. It's tailored to their borough’s housing court +(including information about room numbers and different parts) and factors in +their eligibility for legal representation as well as different types of +eviction proceedings. **This level of personalization is difficult to achieve in +a static site and manage in a CMS.** We wound up finding a solution that gave us +flexibility and reuse of content while preserving the static page nature of +GatsbyJS. + +The four variables for generating these pages were language, housing court, case +type, and eligibility. A quick calculation gave us the basic number of result +pages: + +> **2 languages x 5 different housing courts x 3 different case types x (y/n) +> eligibility = 60 static results pages**! + +This doesn’t include additional pages we built afterwards to account for NYCHA +tenants and other situations. Here’s an example of what this looks like in +Contentful: + +![](housing-court-example.png) + +There are 6 potential pathways that a user could be taken (seen above as +Holdover, Qualifies; Holdover, Doesn’t Qualify, etc) per housing court. These +were represented as *arrays of references* to Housing Court Action Steps, which +are in turn represented in Contentful as editable Markdown snippets. This system +allows for steps to be reused (see “Brooklyn Housing Court location” above) and for +third-party content, such as Google Maps, to be embedded in the steps. To +reorder a step or change a part of the process for a specific court or case +type, you can simply drag-n-drop things in Contentful! + +From there, we had to teach GatsbyJS how to properly render each page based on +pathway. We did this by implementing the `createPages` function in the [Gatsby +Node API](https://www.gatsbyjs.org/docs/node-apis/). For each Housing Court Page +(also per language!), Gatsby creates 6 different pages based on the pathways. +While our solution had to account for some [limitations in +GraphQL](https://github.com/facebook/graphql/issues/414), everything wound up +working as needed. + +Feel free to [explore the source +code](https://github.com/JustFixNYC/eviction-free-nyc) to get a better sense of +how all this works! + + +#### **Wrapping everything up: using Netlify** + +When it came time to deploy, we were very excited to try out a new hosting +platform called [Netlify](https://www.netlify.com/) that we’d been hearing a lot +about. It has a great free tier and is perfect for hosting static sites. We +simply linked Netlify to a branch in the Eviction Free NYC GitHub repo and it +compiles and deploys the site with each push. It simplifies HTTPS certificate +generation and even includes a system for deploying AWS Lambda functions, which +we used to ship a small Twilio integration for the site's “Save to Phone” +feature. *(note: we’re actually still using the original +*[Serverless](https://serverless.com/)* solution, but this code is in the repo +as a to-do)* + +The best feature of Netlify is its ability to utilize build hooks. This allows +us to trigger a new site build when someone edits or adds content from +Contentful. Contentful’s [webhook](https://en.wikipedia.org/wiki/Webhook) +functionality will fire an event when content is edited or published. Once you +link the two together, Netlify will receive the event, rebuild the site, and +deploy everything. Done! + +![](mobile-comps.png) +*Mobile comps for Eviction Free NYC* + +#### In Conclusion + +The technical process for building the site went by incredibly fast — this all +came together in a little over a month! Despite the frenzied speed, we created a +valuable new service that also acts as a launching pad for future feature +development and refinement. **It’s already been used by over 1,000 people in the +past few weeks!** We’re really excited for this site to grow and develop as +tenants take advantage of this historic new right. + +**Footnote: Our code for [evictionfreenyc.org](http://www.evictionfreenyc.org/) is +open source! [Click +here](https://github.com/JustFixNYC/eviction-free-nyc) to view the code on +github.** diff --git a/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/mobile-comps.png b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/mobile-comps.png new file mode 100644 index 0000000000000..aec3f3945c5d7 Binary files /dev/null and b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/mobile-comps.png differ diff --git a/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/provider-example.png b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/provider-example.png new file mode 100644 index 0000000000000..879e22ec30c78 Binary files /dev/null and b/docs/blog/2018-04-27-building-eviction-free-nyc-with-gatsbyjs-and-contentful/provider-example.png differ diff --git a/docs/blog/2018-05-11-six-reasons-i-chose-gatsby/index.md b/docs/blog/2018-05-11-six-reasons-i-chose-gatsby/index.md new file mode 100644 index 0000000000000..43f0262de1284 --- /dev/null +++ b/docs/blog/2018-05-11-six-reasons-i-chose-gatsby/index.md @@ -0,0 +1,41 @@ +--- +title: Six Reasons I Chose Gatsby +date: 2018-05-11 +author: Ray Gesualdo +excerpt: "Spoiler alert: I'm a big fan of Gatsby." +tags: ["gatsby", "react", "graphql", "plugins"] +canonicalLink: https://www.raygesualdo.com/posts/six-reasons-i-chose-gatsby/ +publishedAt: raygesualdo.com +--- + +Spoiler alert: I'm a big fan of [Gatsby](/). I've worked with it multiple times and I'm continually impressed with its power and flexibility. For those who aren't familiar, Gatsby is an open-source static site generator incorporating React and GraphQL. A few weeks ago, I switched my site to Gatsby and wanted to share my reasons for doing so. Plenty of articles have been written about _how_ to build a Gatsby site, but I wanted to talk about _why_ Gatsby is a great choice. I've outlined these reasons below in no particular order (the numbering is only for organizational purposes). I hope they give you a better understanding of Gatsby's benefits and features. + +## #1: It's React + +I've been working with React for the better part of 3.5 years. I know it. I'm efficient in it. Being able to create my site markup with React makes complete sense for me. More than that however, by using React as its templating engine, Gatsby also benefits from all the wonderful React components developed by the community. Like CSS-in-JS? Use it ([styled-components](https://styled-components.com) FTW!). Have a favorite React UI kit? Throw it in there. Any React component that can be server-side rendered, which is most of them, can be used with Gatsby. This opens up a whole new set of possibilities when building out your "static" site. + +## #2: An extensive, well-architected plugin system + +One of the first things about Gatsby that impressed me was its plugin system. Like many other OSS tools such as Webpack and Babel, much of the power of Gatsby is provided by plugins. And that's a good thing. Its plugin architecture allows for incredibly deep integrations into almost every aspect of Gatsby: build configuration, data extraction and transformation, the build process, the browser at runtime, etc. This system has allowed not only the core Gatsby team to create powerful plugins, but the community to create equally powerful plugins as well. I've even tried my hand at [writing one](https://github.com/raygesualdo/gatsby-plugin-settings) (quite successfully, I might add). If there's a task you're looking to accomplish with Gatsby, odds are there is already a plugin for it. And if not, there's [plenty of documentation](/docs/plugin-authoring/) to help you get started writing one. + +## #3: The data fetching layer + +With any website, one needs to have data/content injected into markup to generate HTML. With static site generators, this usually involves writing Markdown files adjacent to template files that get merged together in some way at build time. Gatsby takes a different approach by providing a data fetching abstraction layer between your data/content and your templates. This brings about a huge paradigm shift both in how data is accessed in the templates as well as from where data can be pulled (we'll look at the latter in reason #4). + +With Gatsby, the entirety of your site's data is accessed via a local [GraphQL](https://graphql.org/) API. If you've never worked with GraphQL before, that's okay; Gatsby's docs [walk you through the process](/docs/querying-with-graphql/). In your page templates, you can specify the data you require for that page as a GraphQL query. Then, when Gatsby's build process runs, it analyzes the query and provides the requested data to the template. Future versions of Gatsby will also let you do this at the component level as well. This allows you to build up your templates using the React's normal component paradigm. + +## #4: Multiple data sources + +Because the manner in which one accesses data is abstracted from the data itself, Gatsby can collate data from multiple sources which can then be queried by our templates. This is a significant difference when compared to most static site generators. Instead of only using Markdown files, I can now use any number of different data files locally. But I can also pull data from remote sources such as WordPress, Drupal, Contentful, Stripe, Trello, Medium, MongoDB, and many others. If the data you require can be accessed via an API, you can write a Gatsby source plugin to consume it too. Moreover, any number of these sources can be used in parallel. This allows for powerful and flexible combinations to bring just about any data into your site. I'll be writing a whole blog post on this soon. + +## #5: Performance and PWA features out-of-the-box + +Performance on the web can be difficult. It's especially helpful to have a tool that enforces best practices and optimizes your site by default. Gatsby does just that. When the build process runs, Gatsby creates static HTML files for each of your pages which provides fast initial load times and makes SEO much simpler. Once your page is loaded by the browser though, Gatsby will boot up React and navigate around your site as if you were navigating via a single page app with near-instant transitions without page reloads. Gatsby will even prefetch adjacent/related page content in the background so there's zero delay when your user clicks a link. The client-side experience is buttery smooth with JavaScript enabled and you don't lose any content or navigation if the user has JavaScript dislabed. By adding a single plugin, Gatsby can provide offline support as well, transforming your site into a full-blown Progressive Web App. + +## #6: The developer experience + +This one may be a bit more subjective, but working with Gatsby is plain fun. The plugin system makes it easy to extend, typically with a simple `npm install` and a few lines in the configuration file. When you're developing or writing local content, Gatsby has live-reload so you see your changes immediately. Documentation for the project is solid and keeps improving. The maintainers are extremely helpful on GitHub and Twitter (and I'm sure elsewhere too). It's an all around pleasant experience. + +--- + +Have you used Gatsby before? What are your reasons for using it? Chat with me about them on [Twitter](https://twitter.com/RayGesualdo)! diff --git a/docs/blog/author.yaml b/docs/blog/author.yaml index bdb1505f5565e..686d8780ef249 100644 --- a/docs/blog/author.yaml +++ b/docs/blog/author.yaml @@ -117,7 +117,15 @@ bio: Developer and Diet Coke enthusiast in Brooklyn, NY avatar: avatars/sarah-mogin.jpg twitter: "@sarahmogin" +- id: Dan Kass + bio: Co-founder and engineering lead at JustFix.nyc + avatar: avatars/dan-kass.jpg + twitter: "@JustFixNYC" - id: Gatsby Central bio: The community for gatsby developers avatar: avatars/gatsby-central.jpg twitter: "@GatsbyCentral" +- id: Ray Gesualdo + bio: UI Engineer at SalesLoft. Full-stack JavaScript-er. Speaker. Mentor. Writer. - https://www.raygesualdo.com + avatar: avatars/ray-gesualdo.jpg + twitter: "@RayGesualdo" diff --git a/docs/blog/avatars/dan-kass.jpg b/docs/blog/avatars/dan-kass.jpg new file mode 100644 index 0000000000000..99da99c615da3 Binary files /dev/null and b/docs/blog/avatars/dan-kass.jpg differ diff --git a/docs/blog/avatars/ray-gesualdo.jpg b/docs/blog/avatars/ray-gesualdo.jpg new file mode 100644 index 0000000000000..13ceb3ee63cf9 Binary files /dev/null and b/docs/blog/avatars/ray-gesualdo.jpg differ diff --git a/docs/docs/adding-search.md b/docs/docs/adding-search.md new file mode 100644 index 0000000000000..fd4b0c8d2728f --- /dev/null +++ b/docs/docs/adding-search.md @@ -0,0 +1,61 @@ +--- +title: "Adding search to your Gatsby website" +--- + +Before we go through the steps for adding search to your Gatsby website, let's examine the components needed for adding search to a website. + +There are three required components: + +1. index +2. engine +3. UI + +## Site search components + +### Search index + +The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. + +### Search engine + +The search engine takes a search query, runs it through the search index, and returns any matching documents. + +### Search UI + +The UI component provides an interface to the user, which allows them to write search queries and view the results of each query. + +## Adding search to your site + +Now that you know the three required components, there are a few ways to approach adding search to your Gatsby-powered site. + +### Use an open source search engine + +Using an open source search engine is always free and allows you to enable offline search for your site. Note that you need to be careful with offline search because the entire search index has to be brought into the client, which can affect the bundle size significantly. + +Open source libraries like [`elesticlunr`](https://www.npmjs.com/package/elasticlunr) or [`js-search`](https://github.com/bvaughn/js-search) can be used to enable search for your site. + +Doing so will require you to create a search index when your site is built. For `elesticlunr`, there is a plugin called [`gatsby-plugin-elasticlunr-search`](https://github.com/andrew-codes/gatsby-plugin-elasticlunr-search) that creates a search index automatically. + +For other libraries, you can use a combination of [`onCreateNode`](https://www.gatsbyjs.org/docs/node-apis/#onCreateNode), [`setFieldsOnGraphQLNodeType`](https://www.gatsbyjs.org/docs/node-apis/#setFieldsOnGraphQLNodeType) and [`sourceNodes`](https://www.gatsbyjs.org/docs/node-apis/#sourceNodes) from the Gatsby node API to create the search index and make it available in GraphQL. For more info on how to do this check out [`gatsby-plugin-elasticlunr-search`'s source code](https://github.com/andrew-codes/gatsby-plugin-elasticlunr-search/blob/master/src/gatsby-node.js#L88-L126). + +Another option is to generate the search index at the end of the build using the [`onPostBuild`](https://www.gatsbyjs.org/docs/node-apis/#onPostBuild) node API. + +After building the search index and including it in Gatsby's data layer, you will need to allow the user to search your website. This is typically done by using a text input to capture the search query, then using one of the libraries mentioned above to retrieve the desired document(s). + +### Use an API-based search engine + +Another option is to use an external search engine. This solution is much more scalable as visitors to your site don't have to download your entire search index (which becomes very large as your site grows) in order to search your site. The tradeoff is you'll need to pay for hosting the search engine or pay for a commercial search service. + +There are many available both open source that you can host yourself and commercial hosted options. + +* [ElasticSearch](https://www.elastic.co/products/elasticsearch) — OSS and has commercial hosting available +* [Solr](http://lucene.apache.org/solr/) — OSS and has commercial hosting available +* [Algolia](https://www.algolia.com/) — Commercial + +If you're building a documentation website you can use [Algolia's DocSearch feature](https://community.algolia.com/docsearch/). It will automatically create a search index from the content of your pages. + +If your website does not qualify as documentation, you need to collect the search index at build time and upload it using [`gatsby-plugin-algolia`](https://github.com/algolia/gatsby-plugin-algolia). + +When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. You'll need to implement your own UI; Algolia provides a [React library](https://github.com/algolia/react-instantsearch) which may have components you'd like to use. + +Elasticsearch has several React component libraries for search e.g. https://github.com/appbaseio/reactivesearch diff --git a/docs/docs/building-apps-with-gatsby.md b/docs/docs/building-apps-with-gatsby.md index 4aa5e36b31c6c..7824f4ca58b7f 100644 --- a/docs/docs/building-apps-with-gatsby.md +++ b/docs/docs/building-apps-with-gatsby.md @@ -23,6 +23,8 @@ Often you want to create a site with client-only portions that are gated by auth A classic example would be a site that has a landing page, various marketing pages, a login page, and then an app section for logged-in users. The logged-in section doesn't need to be server rendered as all data will be loaded live from your API after the user logs so it makes sense to make this portion of your site client-only. +Gatsby uses [React Router](https://reacttraining.com/react-router/) under the hood. You should use React Router to create client-only routes. + These routes will exist on the client only and will not correspond to index.html files in an app's built assets. If you wish people to visit client routes directly, you'll need to setup your server to handle these correctly. To create client-only routes, you want to add code to your site's `gatsby-node.js` like the following: diff --git a/docs/docs/custom-html.md b/docs/docs/custom-html.md index b49ffe4e73b91..a6c250b61df41 100644 --- a/docs/docs/custom-html.md +++ b/docs/docs/custom-html.md @@ -13,7 +13,7 @@ tree by running: cp .cache/default-html.js src/html.js ``` -And then making modifications as needed. +And then make modifications as needed. ### Required props @@ -22,7 +22,7 @@ Note: the various props that are rendered into pages _are_ required e.g. ### React Helmet -Also anything you render in the `html.js` component will _not_ be made "live" in +Also, anything you render in the `html.js` component will _not_ be made "live" in the client like other components. If you want to dynamically update your `` we recommend using [React Helmet](/packages/gatsby-plugin-react-helmet/) diff --git a/docs/docs/deploy-gatsby.md b/docs/docs/deploy-gatsby.md index 5ee3625ed4350..56d0fa10cf0cf 100644 --- a/docs/docs/deploy-gatsby.md +++ b/docs/docs/deploy-gatsby.md @@ -152,9 +152,18 @@ module.exports = { ### Build and Deploy with GitLab CI To use GitLab's continuous integration (CI), you need to add a `.gitlab-ci.yml` -configuration file. This can be added into your project folder, or once you have -pushed the repository, you can add it with GitLab's website. The file needs to -contain a few required fields: +configuration file. This is the file that Gitlab uses to manage the CI job. + +It can easily be added to your repository by the [Gitlab](https://gitlab.com) +website, as the online editor contains a pre-built template for Gatsby deployment. + +To use the template open your repository on their website, select the 'Setup CI/CD' option on +the center menu, and it will create a new blank `.gitlab-ci.yml` for you. Now +select the 'Apply a Gitlab CI Yaml Template' drop-down, and type 'Gatsby' into +the filter. Select the Gatsby option, click 'Commit Changes', and you are done! + +If adding this manually to your project, the file needs to contain a few required +fields: ``` image: node:latest diff --git a/docs/docs/gatsby-starters.md b/docs/docs/gatsby-starters.md index ff4a9f7cb110f..b7c248a6350f9 100644 --- a/docs/docs/gatsby-starters.md +++ b/docs/docs/gatsby-starters.md @@ -168,6 +168,17 @@ Community: * TypeScript +* [gatsby-starter-bulma-storybook](https://github.com/gvaldambrini/gatsby-starter-bulma-storybook) + [(demo)](http://gatsby-bulma-storybook.surge.sh/) + + Features: + + * Storybook for developing components in isolation + * Bulma and Sass support for styling + * CSS modules + * Prettier & eslint to format & check the code + * Jest + * [gatsby-starter-default-i18n](https://github.com/angeloocana/gatsby-starter-default-i18n) [(demo)](https://gatsby-starter-default-i18n.netlify.com) @@ -617,7 +628,7 @@ Community: * Disqus and Share Support * [gatsby-advanced-blog](https://github.com/wonism/gatsby-advanced-blog) - [(demo)](https://kind-cori-836fe1.netlify.com/) + [(demo)](https://wonism.github.io/) Features: @@ -661,3 +672,19 @@ Community: * Google Analytics integration * Open Sans font using Google Fonts * Prerendered Open Graph tags for rich sharing + +* [gatsby-starter-modern](https://github.com/kripod/gatsby-starter-modern) + [(demo)](https://gatsby-starter-modern-demo.netlify.com/) + + Features: + + * Built on the upcoming version of Gatsby + * A set of strict linting rules (based on the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)) + * `lint` script + * Encourage automatic code formatting + * `format` script + * Prefer using [Yarn](https://yarnpkg.com) for package management + * Use [EditorConfig](http://editorconfig.org) to maintain consistent coding styles between different editors and IDEs + * Integration with [Visual Studio Code](https://code.visualstudio.com) + * Pre-configured auto-formatting on file save + * Based on [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default) diff --git a/docs/docs/gatsby-style-guide.md b/docs/docs/gatsby-style-guide.md index b3bb76cba3942..47839f352be49 100644 --- a/docs/docs/gatsby-style-guide.md +++ b/docs/docs/gatsby-style-guide.md @@ -170,7 +170,8 @@ abstract syntax tree (AST) is ..." Text should use the second person ("you") to help to give it a conversational tone. This way, the text and instructions seem to speak directly to the person -reading it. Try to avoid using the first person ("I", "we", "let's", and "us"). +reading it. Try to avoid using the first person ("I", "we", "let's", and "us"). +Using second person is also more accurate than saying "we," because typically only one person is reading the tutorial or guide at a time and the person who wrote the tutorial is not actually going through it with them, so "we" would be inaccurate. Finally, some technical documentation uses third person pronouns and nouns like "they" and "the user," which add more distance and feel colder than the conversational and warm "you" and "your." If there are other Guide resources you think readers would benefit from, add them at the bottom in an "Other Resources" section. @@ -192,6 +193,12 @@ item in a list of three or more items, before ‘and’ or ‘or’ e.g. an Ital painter, sculptor, and architect). It makes things easier, clearer, and prettier to read. +Avoid using words like "easier" or "simple," because if users have a hard time completing the task that is supposedly "easy," they will question their abilities. Consider using more specific descriptors; for example, when you say the phrase "deployment is easy," what do you really mean? Is it easy because it takes fewer steps than another option? If so, just use the most specific descriptor possible, which in that case would be "this deployment method involves fewer steps than other options." + +Hyperlinks should contain the clearest words to indicate where the link will lead you. So instead of linking to the word [here](https://www.gatsbyjs.org/) link to [Gatsby's docs](https://www.gatsbyjs.org/). + +When a paragraph or sentence offers an optional path, the beginning of the first sentence should indicate optionality. For example, "if you'd like to learn more about xyz, see our reference guide" is clearer than "Go to the reference guide if you'd like to learn more about xyz." This method allows people who would *not* like to learn more about xyz to stop reading the sentence as early as possible. This method also allows people who *would* like to learn more about xyz to recognize the opportunity to learn quicker instead of skipping over the paragraph. + # Formatting example code Readers will likely use Guide articles as a quick reference to look up syntax. diff --git a/docs/docs/how-gatsby-works-with-github-pages.md b/docs/docs/how-gatsby-works-with-github-pages.md index c69f8d0537101..fdc9494bd51c3 100644 --- a/docs/docs/how-gatsby-works-with-github-pages.md +++ b/docs/docs/how-gatsby-works-with-github-pages.md @@ -47,4 +47,4 @@ After running `npm run deploy` you should see your website at `http://username.g ## Custom domains -If you use a [custom domain](https://help.github.com/articles/using-a-custom-domain-with-github-pages/), don't add a `pathPrefix` as it will break navigation on your site. Path prefixing is only necessary when the site is _not_ at the root of the domain like with repository sites. +If you use a [custom domain](https://help.github.com/articles/using-a-custom-domain-with-github-pages/), don't add a `pathPrefix` as it will break navigation on your site. Path prefixing is only necessary when the site is _not_ at the root of the domain like with repository sites. Also don't forget to add your [CNAME](https://help.github.com/articles/troubleshooting-custom-domains/#github-repository-setup-errors) file to the `static` directory. diff --git a/docs/docs/how-to-contribute.md b/docs/docs/how-to-contribute.md deleted file mode 120000 index f939e75f21a8b..0000000000000 --- a/docs/docs/how-to-contribute.md +++ /dev/null @@ -1 +0,0 @@ -../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/docs/how-to-contribute.md b/docs/docs/how-to-contribute.md new file mode 100644 index 0000000000000..61ee1ee92dec2 --- /dev/null +++ b/docs/docs/how-to-contribute.md @@ -0,0 +1,130 @@ +--- +title: How to Contribute +--- + +## Contributing + +We want contributing to Gatsby to be fun, enjoyable, and educational for anyone and everyone. Contributions go far beyond pull requests and commits; we are thrilled to receive a variety of other contributions including the following: + +* Blogging, speaking about, or creating tutorials about one of Gatsby's many features. Mention @gatsbyjs on Twitter and/or email shannon [at] gatsbyjs [dot] com so we can give pointers and tips (if you want them :) and help you spread the word. Please add your blog posts and videos of talks to our [Awesome Gatsby](/docs/awesome-gatsby/) page. +* [Submit new feature ideas through an RFC](/blog/2018-04-06-introducing-gatsby-rfc-process/) +* Submitting new documentation; titles in _italics_ on gatsbyjs.org are stubs and need contributions +* Tweeting about things you build with @gatsbyjs (make sure to @ mention us!) +* Submitting documentation updates, enhancements, designs, or bugfixes +* Submitting spelling or grammar fixes +* Adding unit or functional tests +* Triaging [GitHub issues](https://github.com/gatsbyjs/gatsby/issues) -- especially determining whether an issue still persists or is reproducible +* [Reporting bugs or issues](/docs/how-to-file-an-issue/) +* Searching for Gatsby on Discord or Spectrum and helping someone else who needs help +* Teaching others how to contribute to Gatsby's repo! + +If you are worried or don't know where to start, you can always reach out to Shannon Soper(@shannonb_ux) on Twitter or simply submit an issue and a maintainer can help give you guidance! + +Looking to speak about Gatsby? We'd love to review your talk abstract/CFP! You can email it to shannon [at] gatsbyjs [dot] com, and we can give pointers or tips!!! + +### Creating your own plugins and loaders + +If you create a loader or plugin, we would <3 for you to open source it and put it on npm. For more information on creating custom plugins, please see the documentation for [plugins](/docs/plugins/) and the [API specification](/docs/api-specification/). + +### Contributing to the repo + +Gatsby uses a "monorepo" pattern to manage its many dependencies and relies on +lerna and yarn to configure the repository for active development. + +You can install the latest version of Gatsby by following these steps: + +* Clone the repo, navigate to its directory. +* ensure you have the latest version of yarn installed (>= 1.0.2) + https://yarnpkg.com/en/docs/install +* Install dependencies using `yarn run bootstrap` in the root of the repo. + +The usual contributing steps are: + +* Fork the [official repository](https://github.com/gatsbyjs/gatsby). +* Clone your fork: `git clone https://github.com//gatsby.git` +* Setup up repo and install dependencies: `yarn run bootstrap` +* Make sure tests are passing for you: `yarn test` +* Create a topic branch: `git checkout -b topics/new-feature-name` +* Run `npm run watch` from the root of the repo to watch for changes to packages' source code and compile these changes on-the-fly as you work. Note that the watch command can be resource intensive. To limit it to the packages you're working on, add a scope flag, like `npm run watch -- --scope={gatsby,gatsby-cli}`. To watch just one package, run `npm run watch -- --scope=gatsby`. +* Install [gatsby-dev-cli](/packages/gatsby-dev-cli/) globally: `yarn global add gatsby-dev-cli` +* Run `yarn install` in each of the sites you're testing. +* For each of your Gatsby test sites, run the `gatsby-dev` command there to copy + the built files from your cloned copy of Gatsby. It'll watch for your changes + to Gatsby packages and copy them into the site. For more detailed instructions + see the [gatsby-dev-cli README](/packages/gatsby-dev-cli/) +* Add tests and code for your changes. +* Once you're done, make sure all tests still pass: `yarn test` +* Commit with a ["Signed-off-by"](#developer-certificate-of-origin) line appended + to your commit message and push to your fork. +* Create a pull request from your branch. + +### Contributing to the documentation. + +Gatsby, unsurprisingly, uses Gatsby for its documentation website. + +If you want to add/modify any Gatsby documentation, go to the +[docs folder on GitHub](https://github.com/gatsbyjs/gatsby/tree/master/docs) and +use the file editor to edit and then preview your changes. GitHub then allows +you to commit the change and raise a PR right in the UI. This is the _easiest_ +way you can contribute to the project! + +However, if you want to make more changes to the website, that is, change +layouts, add sections/pages, follow the steps below. You can then spin up your +own instance of the Gatsby website and make/preview your changes before raising +a pull request. + +* Clone the repo and navigate to `/www` +* Run `yarn` to install all of the website's dependencies. +* Run `gatsby develop` to preview the website in `http://localhost:8000` +* The Markdown files for the documentation live in `/docs` folder. Make + additions or modifications here. +* Make sure to double check your grammar and capitalise correctly. +* Commit with a ["Signed-off-by"](#developer-certificate-of-origin) line appended + to your commit message and push to your fork. +* Create a pull request from your branch. + +## Development tools + +### Redux devtools + +Gatsby uses Redux for managing state during development and building. It's often +helpful to see the flow of actions and built-up state for a site you're working +on or if adding new functionality to core. We leverage +[Remote Redux Devtools](https://github.com/zalmoxisus/remote-redux-devtools) and +[RemoteDev Server](https://github.com/zalmoxisus/remotedev-server) to give you use the Redux +devtools extension for debugging Gatsby. + +To use this, first install +[redux-devtools-extension](https://github.com/zalmoxisus/redux-devtools-extension) +in your browser. Then in your Gatsby repo, run `npm run remotedev`. Then in your +site directory run `REDUX_DEVTOOLS=true gatsby develop`. Depending on your +operating system and shell, you may need to modify how you set the +`REDUX_DEVTOOLS` environment variable. + +At this point, your site will be sending Redux actions and state to the remote +server. + +To connect to this, you need to setup the devtools extension to talk to the +remote server. + +First open the remote devtools. + +![how to open the redux remote devtools extension](./images/open-remote-dev-tools.png) + +Then click settings along the bottom menu and set the host and port. + +![how to set the host/port for the remote devtools extension to connect to Gatsby](./images/remote-dev-settings.png) + +After this, the devtools extension _should_ connect to the remote server and +you'll see actions start showing up. + +![gatsby redux remote devtools](./images/running-redux-devtools.png) + +**Warning!! Lots of bugginess**. While having this available is extremely +helpful, this setup is very buggy and fragile. There is a memory leak in the +extension that's triggered it seems every time you restart the Gatsby +development server. Also the extension often, for no apparent reason, just won't +show any actions from the remote server. It'll also often freeze up. The best +solution seems to just be turning everything off and on again. Fixing up these +tools would be very helpful for us and many others using these tools if someone +wants to take this on! diff --git a/docs/docs/image-tutorial.md b/docs/docs/image-tutorial.md new file mode 100644 index 0000000000000..583694a279d83 --- /dev/null +++ b/docs/docs/image-tutorial.md @@ -0,0 +1,262 @@ +## The Gatsby Way™ of rendering images + +Using images pulled from a WordPress demo CMS + +### What this tutorial covers: + +In this tutorial, you will install the several image plugins and components in order to pull image data from a WordPress account into your Gatsby site and render that data. This [Gatsby + Wordpress demo site](https://using-wordpress.gatsbyjs.org/sample-post-1) shows you a sample of what you’re going to be building in this tutorial, although in this tutorial you’ll just focus on adding images. + +### Why go through this tutorial? + +Images are one of the most beautiful and striking ways to communicate to people, and are a key part of creating an effective and positive user experience; at the same time, high quality images can load slowly and cause text boxes to jump around, both of which make it difficult for people to be patient with visiting your website. + +The Gatsby Way™ of creating images is a phrase we made up to describe a set of best practices that help you optimize performance and responsiveness of images. This [Gatsbygram site](https://gatsbygram.gatsbyjs.org/) (an Instagram feed fed through Gatsby) shows off the svg image tracing effect. Here’s an [image processing demo site](https://image-processing.gatsbyjs.org/) exploring how to have fun with images in your Gatsby site. + +### Installing the `gatsby-source-wordpress` plugin + +First you’ll need to install the `gatsby-source-wordpress` plugin that has images ready for you to pull into your site. + +Create a new Gatsby project and change directories into the new project you just created: +```shell +gatsby new images-tutorial-site +cd images-tutorial-site +``` + +Install the `gatsby-source-wordpress` plugin. For extra reading on the plugin’s features and examples of GraphQL queries not included in this tutorial, see the [`gatsby-source-wordpress` plugin’s READme file](https://www.gatsbyjs.org/packages/gatsby-source-wordpress/?=wordpress). + +```shell +npm install --save gatsby-source-wordpress +``` + +Add the `gatsby-source-wordpress` plugin to `gatsby-config.js` using the following code, which you can also find in the [demo site’s source code](https://github.com/gatsbyjs/gatsby/blob/master/examples/using-wordpress/gatsby-config.js). + +```javascript{32-58} + module.exports = { + siteMetadata: { + title: 'Gatsby Wordpress Tutorial', + }, + plugins: [ + // https://public-api.wordpress.com/wp/v2/sites/gatsbyjsexamplewordpress.wordpress.com/pages/ + /* + * Gatsby's data processing layer begins with “source” + * plugins. Here the site sources its data from Wordpress. + */ + { + resolve: `gatsby-source-wordpress`, + options: { + /* + * The base URL of the Wordpress site without the trailingslash and the protocol. This is required. + * Example : 'gatsbyjswpexample.wordpress.com' or 'www.example-site.com' + */ + baseUrl: `dev-gatbsyjswp.pantheonsite.io`, + // The protocol. This can be http or https. + protocol: `http`, + // Indicates whether the site is hosted on wordpress.com. + // If false, then the assumption is made that the site is self hosted. + // If true, then the plugin will source its content on wordpress.com using the JSON REST API V2. + // If your site is hosted on wordpress.org, then set this to false. + hostingWPCOM: false, + // If useACF is true, then the source plugin will try to import the Wordpress ACF Plugin contents. + // This feature is untested for sites hosted on Wordpress.com + useACF: true, + }, + }, + ], +} +``` + +### Installing plugins to help with images +Now you’ll configure gatsby-source-filesystem to load the image directory, add a GraphQL query to a page, add an image to the page, and then view the result in the browser. +First, you’ll need to install a few plugins and their dependencies: + +```shell +npm install --save gatsby-transformer-sharp gatsby-plugin-sharp gatsby-image +``` + +Place these plugins in your `gatsby-config.js` like this: + +```javascript{112-121} +module.exports = { + siteMetadata: { + title: 'Gatsby Wordpress Tutorial', + }, + plugins: [ + // https://public-api.wordpress.com/wp/v2/sites/gatsbyjsexamplewordpress.wordpress.com/pages/ + /* + * Gatsby's data processing layer begins with “source” + * plugins. Here the site sources its data from Wordpress. + */ + { + resolve: `gatsby-source-wordpress`, + options: { + /* + * The base URL of the Wordpress site without the trailing slash and the protocol. This is required. + * Example : 'gatsbyjswpexample.wordpress.com' or 'www.example-site.com' + */ + baseUrl: `dev-gatbsyjswp.pantheonsite.io`, + // The protocol. This can be http or https. + protocol: `http`, + // Indicates whether the site is hosted on wordpress.com. + // If false, then the asumption is made that the site is self hosted. + // If true, then the plugin will source its content on wordpress.com using the JSON REST API V2. + // If your site is hosted on wordpress.org, then set this to false. + hostingWPCOM: false, + // If useACF is true, then the source plugin will try to import the Wordpress ACF Plugin contents. + // This feature is untested for sites hosted on Wordpress.com + useACF: true, + }, + }, + 'gatsby-plugin-react-helmet', + 'gatsby-transformer-sharp', + 'gatsby-plugin-sharp', + ], +} +``` + +### Creating GraphQL queries that pull in images from WordPress + +Now you are ready to create a GraphQL query to pull in some images from the WordPress site. + +Run: + +```shell +gatsby develop +``` + +Open localhost:8000 and localhost:8000/___graphql. + +Here’s an example of creating specific widths and heights for images: + +```jsx +{ + allWordpressPost { + edges { + node { + childWordPressAcfPostPhoto { + photo { + localFile { + childImageSharp { + # Try editing the "width" and "height" values. + resolutions(width: 200, height: 200) { + # In the GraphQL explorer, use field names + # like "src". In your site's code, remove them + # and use the fragments provided by Gatsby. + src + + # This fragment won't work in the GraphQL + # explorer, but you can use it in your site. + # ...GatsbyImageSharpResolutions_withWebp + } + } + } + } + } + } + } + } +} +``` + + +Here’s an example query for generating different sizes of an image: + +```jsx +{ + allWordpressPost { + edges { + node { + childWordPressAcfPostPhoto { + photo { + localFile { + childImageSharp { + # Try editing the "maxWidth" value to generate resized images. + sizes(maxWidth: 500) { + # In the GraphQL explorer, use field names + # like "src". In your site's code, remove them + # and use the fragments provided by Gatsby. + src + + # This fragment won't work in the GraphQL + # explorer, but you can use it in your site + # ...GatsbyImageSharpSizes_withWebp + } + } + } + } + } + } + } + } +} +``` + +In either case, you can add traced SVG support by adding `_tracedSVG` to the end of each fragment. _Note this won’t work in the GraphQL explorer._ + +### Rendering the images to `index.js` + +Here is what your `index.js` should look like with the query added: + +```jsx +import React from 'react' +import Link from 'gatsby-link' +import Img from 'gatsby-image' + +const IndexPage = ({ data }) => { + const imagesResolutions = data.allWordpressPost.edges.map( + edge => + edge.node.childWordPressAcfPostPhoto.photo.localFile.childImageSharp + .resolutions + ) + return ( +
+

Hi people

+

Welcome to your new Gatsby site.

+

Now go build something great.

+ {imagesResolutions.map(imageRes => ( + + ))} + Go to page 2 +
+ ) +} + +export default IndexPage + +export const query = graphql` + query ImageQuery { + allWordpressPost { + edges { + node { + childWordPressAcfPostPhoto { + photo { + localFile { + childImageSharp { + # edit the maxWidth value to generate resized images + resolutions(width: 500, height: 500) { + ...GatsbyImageSharpResolutions_withWebp_tracedSVG + } + } + } + } + } + } + } + } + } +` +``` + +Your demo site should look something like this: + +![Demo site example](./images/wordpress-image-tutorial.gif) + +### Testing your image loading speed and effects +It is useful and can be fun to purposefully slow down your browser to see image effects animate more slowly. + +Open your browser console and change the network speed to something slower. In Chrome, you can click on the “network” tab, then on the drop down arrow next to the word “Online.” Then click “Slow 3G.” Now, reload your page and watch the blur-up and SVG effects in action. The network tab also shows statistics on when each image loaded and how much time it took them to load. + +![Network](./images/network.png) + +![Slow 3G](./images/slow-3g.png) + + diff --git a/docs/docs/images/network.png b/docs/docs/images/network.png new file mode 100644 index 0000000000000..965306264e786 Binary files /dev/null and b/docs/docs/images/network.png differ diff --git a/docs/docs/images/slow-3g.png b/docs/docs/images/slow-3g.png new file mode 100644 index 0000000000000..a002f3c6dfdc2 Binary files /dev/null and b/docs/docs/images/slow-3g.png differ diff --git a/docs/docs/images/wordpress-image-tutorial.gif b/docs/docs/images/wordpress-image-tutorial.gif new file mode 100644 index 0000000000000..230e3697bcbae Binary files /dev/null and b/docs/docs/images/wordpress-image-tutorial.gif differ diff --git a/docs/docs/local-https.md b/docs/docs/local-https.md index ff47638a9b1a1..4837dda927c80 100644 --- a/docs/docs/local-https.md +++ b/docs/docs/local-https.md @@ -4,7 +4,7 @@ title: "Local HTTPS" Gatsby provides an easy way to use a local HTTPS server during development, thanks to [devcert](https://github.com/davewasmer/devcert). When you enable the `https` option, a private key and certificate file will be created for your project and used by the development server. -## Usage +## Usage (Automatic HTTPS) Start the development server using `gatsby develop` as usual, and add either the `-S` or `--https` flag. @@ -33,6 +33,21 @@ Now open the development server at [https://localhost:8000](https://localhost:80 Find out more about [how devcert works](https://github.com/davewasmer/devcert#how-it-works). +## Custom Key and Certificate Files + +You may find that you need a custom key and certificate file for https if you use multiple +machines for development (or if your dev environment is containerized in Docker). + +If you need to use a custom https setup, you can pass the `--https`, `--key-file` and +`--cert-file` flags to `gatsby develop`. + + - `--cert-file` [relative path to ssl certificate file] + - `--key-file` [relative path to ssl key file] + + $ gatsby develop --https --key-file ../relative/path/to/key.key --cert-file ../relative/path/to/cert.crt + +in most cases, the `--https` passed by itself is easier and more convenient to get local https. + --- -Keep in mind that the certificates are explicitly issued to `localhost` and will only be accepted there. Using it together with the `--host` option will likely result in browser warnings. +Keep in mind that the automatic certificates issued with the `--https` flag are explicitly issued to `localhost` and will only be accepted there. Using it together with the `--host` option will likely result in browser warnings. diff --git a/docs/docs/netlify-cms.md b/docs/docs/netlify-cms.md index 86efc5363f496..85996c4cc82fc 100644 --- a/docs/docs/netlify-cms.md +++ b/docs/docs/netlify-cms.md @@ -63,6 +63,7 @@ backend: name: test-repo media_folder: static/assets +public_folder: assets collections: - name: blog @@ -73,6 +74,7 @@ collections: - { name: path, label: Path } - { name: date, label: Date, widget: date } - { name: title, label: Title } + - { name: body, label: Body, widget: markdown } ``` Then in your terminal run `gatsby develop` to start the Gatsby development server. Once the server diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index aec3d0f4538f9..e94bd8dd2226d 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -35,4 +35,37 @@ module.exports = { } ``` -Plugins can take options. Note that plugin options will be stringified by Gatsby, so they cannot be functions. +Plugins can take options. Examples: + +```javascript +module.exports = { + plugins: [ + // Shortcut for adding plugins without options. + 'gatsby-plugin-react-helmet', + { + // Standard plugin with options example + resolve: `gatsby-source-filesystem`, + options: { + path: `${__dirname}/src/data/`, + name: 'data', + }, + }, + { + resolve: 'gatsby-plugin-offline', + // Blank options, equivalent to string-only plugin + options: { + plugins: [], + }, + }, + { + resolve: `gatsby-transformer-remark`, + options: { + // plugins inside plugins + plugins: [`gatsby-remark-smartypants`], + }, + }, + ], +} +``` + +Note that plugin options will be stringified by Gatsby, so they cannot be functions. diff --git a/docs/docs/source-plugin-tutorial.md b/docs/docs/source-plugin-tutorial.md new file mode 100644 index 0000000000000..6e1059635c3a6 --- /dev/null +++ b/docs/docs/source-plugin-tutorial.md @@ -0,0 +1,395 @@ +--- +title: "Source plugin tutorial" +--- + +Creating your own source plugin. + +## What this tutorial covers + +In this tutorial you'll create your own source plugin. Your plugin will source data from [pixabay.com](https://pixabay.com) allowing you to add Pixabay images to any Gatsby site. + +## What is a source plugin? + +Source plugins "source" data from remote or local locations into what Gatsby calls [nodes](/docs/node-interface/). + +For more background on source plugins, check out [Gatsby's source plugin documentation](/docs/create-source-plugin/) + +## Why create a source plugin? + +Source plugins convert data from any source into a format that can be processed by Gatsby. Your Gatsby site could use several source plugins to combine data in interesting ways. + +If you can't find a plugin for your data source you can create your own. + +## How to create a source plugin + +### Overview + +Your plugin is going to source images from Pixabay. You'll be able to configure your plugin in your site's `gatsby-config.js` file and write GraphQL queries to access your plugin's data. + +> **NOTE:** You'll need a Pixabay API key which you can get by [registering for a Pixabay account](https://pixabay.com/en/accounts/register/). Your API key is in the [“Search Images” section of the Pixabay API docs](https://pixabay.com/api/docs/#api_search_images). + +### An example API request + +Pixabay's [API documentation](https://pixabay.com/api/docs/#api_search_images) describes how their API works. Here's an example that uses a few options to search for photos: + +`https://pixabay.com/api/?q=yellow+flowers&editors_choice=true&pretty=true&key=` + +Take the above URL and paste it in to a browser to see Pixabay's response to your query. It gives you a list of photos matching the query "yellow flowers" that have received an Editor's Choice award. + +> **NOTE:** You should replace with your Pixabay API key. + +### Plugin behavior + +Your plugin will have the following behavior: + +* Accept config options like a Pixabay API key and a search query +* Make an API request using the provided config options +* Convert the data in the API response to Gatsby's node system + +### Setup a new Gatsby site + +Create a new Gatsby project and change directories into the new project you just created. + +```shell +gatsby new source-tutorial-site +cd source-tutorial-site +``` + +You're going to build your plugin as a "local" plugin that only exists for your project. Later on you'll learn how to publish a plugin to [npm](https://npmjs.com) so anyone can use it, but for now create a `plugins` directory and change into that directory: + +```shell +mkdir plugins +cd plugins +``` + +### Create a `plugins` folder + +The bare essentials of a plugin are a directory named after your plugin, which contains a `package.json` file and a `gatsby-node.js` file: + +``` +|-- plugins + |-- gatsby-source-pixabay + |-- gatsby-node.js + |-- package.json +``` + +Start by creating the directory and changing into it: + +``` +mkdir gatsby-source-pixabay +cd gatsby-source-pixabay +``` + +### Create a `package.json` file + +Now create a `package.json` file, this describes your plugin and any third-party code it might depend on. `npm` has a command to create this file for you. Run: + +```shell +npm init --yes +``` + +to create the file using default options. + +> **NOTE:** You can omit `--yes` if you'd like to specify the options yourself. + +### Add dependencies + +You'll use a couple of modules from npm to add some helper functionality. Install them with: + +```shell +npm install node-fetch query-string --save +``` + +Open your `package.json` file and you'll see `node-fetch` and `query-string` have been added to a `dependencies` section at the end: + +```js + "dependencies": { + "node-fetch": "^2.1.2", + "query-string": "^6.0.0" + } +``` + +With the setup done, move on to adding the plugin's functionality. + +### Create a `gatsby-node.js` file + +Create a new file called `gatsby-node.js` in your `gatsby-source-pixabay` directory, and add the following: + +```js +const crypto = require("crypto"); +const fetch = require("node-fetch"); +const queryString = require("query-string"); + +exports.sourceNodes = ( + { boundActionCreators, createNodeId }, + configOptions +) => { + const { createNode } = boundActionCreators; + + // Gatsby adds a configOption that's not needed for this plugin, delete it + delete configOptions.plugins; + + // plugin code goes here... + console.log("Testing my plugin", configOptions); +}; +``` + +### Step by step through your `gatsby-node.js` file + +What did you do by adding this code? You started by importing the dependencies that you added earlier (along with one built in dependency): + +```js +const crypto = require("crypto"); +const fetch = require("node-fetch"); +const queryString = require("query-string"); +``` + +Then you implemented Gatsby's [`sourceNodes` API](/docs/node-apis/#sourceNodes) which Gatsby will run as part of its bootstrap process. When Gatsby calls `sourceNodes`, it'll pass in some helper functions (`boundActionCreators` and `createNodeId`) along with any config options that are provided in your project's `gatsby-config.js` file: + +```js +exports.sourceNodes = ( + { boundActionCreators, createNodeId }, + configOptions +) => { +``` + +You do some initial setup: + +```js +const { createNode } = boundActionCreators; + +// Gatsby adds a configOption that's not needed for this plugin, delete it +delete configOptions.plugins; +``` + +And finally add a placeholder message: + +```js +// plugin code goes here... +console.log("Testing my plugin", configOptions); +``` + +### Add the plugin to your site + +The skeleton of your plugin is in place which means you can add it to your project and check your progress so far. + +Open `gatsby-config.js` from the root directory of your tutorial site, and add the `gatsby-source-pixabay` plugin: + +```js +module.exports = { + siteMetadata: { + title: "Gatsby Default Starter", + }, + plugins: [ + "gatsby-plugin-react-helmet", + { + resolve: "gatsby-source-pixabay", + options: { + key: "", + q: "yellow flowers", + }, + }, + ], +}; +``` + +Open a new terminal in the root directory of your tutorial site, then start Gatsby's development mode: + +```shell +gatsby develop +``` + +Check the lines after `success on PreBootstrap`, you should see your "Testing my plugin" message along with the `key` from your `gatsby-config.js` file: + +```shell +success onPreBootstrap — 0.048 s +⠁ Testing my plugin { key: '' } +warning The gatsby-source-pixabay plugin has generated no Gatsby nodes. Do you need it? +success source and transform nodes — 0.057 s +``` + +Note that Gatsby is warning that your plugin doesn't do anything yet. Time to fix that. + +### Fetch remote data from Pixabay + +Update `gatsby-node.js` in your `plugins/gatsby-source-pixabay/` directory: + +```js{14-32} +const fetch = require('node-fetch') +const queryString = require('query-string') +const crypto = require('crypto') + +exports.sourceNodes = ( + { boundActionCreators, createNodeId }, + configOptions +) => { + const { createNode } = boundActionCreators + + // Gatsby adds a configOption that's not needed for this plugin, delete it + delete configOptions.plugins + + // Convert the options object into a query string + const apiOptions = queryString.stringify(configOptions) + + // Join apiOptions with the Pixabay API URL + const apiUrl = `https://pixabay.com/api/?${apiOptions}` + + // Gatsby expects sourceNodes to return a promise + return ( + // Fetch a response from the apiUrl + fetch(apiUrl) + // Parse the response as JSON + .then(response => response.json()) + // Process the JSON data into a node + .then(data => { + // For each query result (or 'hit') + data.hits.forEach(photo => { + console.log("Photo data is:", photo) + }) + }) + ) +} +``` + +You've added code that fetches photo data from the Pixabay API. For now, your plugin logs that data but doesn't do anything else. Check that you can see the logged photo data by restarting `gatsby develop`. This time you should see a series of results like: + +```shell +success onPreBootstrap — 0.035 s +⠠ source and transform nodesresponse Response { size: 0, timeout: 0 } +Photo data is: { largeImageURL: 'https://pixabay.com/get/ea36b70d29fd073ed1584d05fb1d4e9ee570e4d510ac104497f5c071a3efb6bd_1280.jpg', + webformatHeight: 426, + webformatWidth: 640, + likes: 17, + imageWidth: 5184, + id: 3362196, + user_id: 5598375, + views: 263, + comments: 24, + pageURL: 'https://pixabay.com/en/dandelion-flower-yellow-nature-3362196/', + imageHeight: 3456, + + ...(more data follows)... +``` + +You're ready to add the final step of your plugin - converting this data into a Gatsby node. + +### Use `createNode` function + +You're adding a helper function on lines 15 to 35 and processing the data into a node on lines 52 to 55: + +```js{15-35,52-55} +const fetch = require('node-fetch') +const queryString = require('query-string') +const crypto = require('crypto') + +exports.sourceNodes = ( + { boundActionCreators, createNodeId }, + configOptions +) => { + const { createNode } = boundActionCreators + + // Gatsby adds a configOption that's not needed for this plugin, delete it + delete configOptions.plugins + + // Helper function that processes a photo to match Gatsby's node structure + const processPhoto = photo => { + const nodeId = createNodeId(`pixabay-photo-${photo.id}`) + const nodeContent = JSON.stringify(photo) + const nodeContentDigest = crypto + .createHash('md5') + .update(nodeContent) + .digest('hex') + + const nodeData = Object.assign({}, photo, { + id: nodeId, + parent: null, + children: [], + internal: { + type: `PixabayPhoto`, + content: nodeContent, + contentDigest: nodeContentDigest, + }, + }) + + return nodeData + } + + // Convert the options object into a query string + const apiOptions = queryString.stringify(configOptions) + + // Join apiOptions with the Pixabay API URL + const apiUrl = `https://pixabay.com/api/?${apiOptions}` + + // Gatsby expects sourceNodes to return a promise + return ( + // Fetch a response from the apiUrl + fetch(apiUrl) + // Parse the response as JSON + .then(response => response.json()) + // Process the response data into a node + .then(data => { + // For each query result (or 'hit') + data.hits.forEach(photo => { + // Process the photo data to match the structure of a Gatsby node + const nodeData = processPhoto(photo) + // Use Gatsby's createNode helper to create a node from the node data + createNode(nodeData) + }) + }) + ) +} +``` + +### Query for results + +Your plugin is ready. Restart `gatsby develop` and open a browser at [http://localhost:8000/\_\_\_graphql](http://localhost:8000/___graphql). The Pixabay data can be queried from here. try: + +```graphql +{ + allPixabayPhoto(limit: 10) { + edges { + node { + largeImageURL + pageURL + tags + user + } + } + } +} +``` + +Or [open the query from this link](). + +Experiment with different options in your `gatsby-config.js` file to see how that affects your query results. The [Pixabay API docs](https://pixabay.com/api/docs/#api_search_images) might be a useful reference. + +## Publishing a plugin + +You've built a local plugin for your project, but what if you want to share it with others? `npm` allows you to publish your plugins. Check out the npm docs on [How to Publish & Update a Package](https://docs.npmjs.com/getting-started/publishing-npm-packages) for more info. + +> **NOTE:** Don't forget to edit your plugin's `package.json` file to include info about your plugin. + +## Summary + +You've written a local Gatsby plugin that: + +* can be configured with an entry in your `gatsby-config.js` file +* requests data from a third-party API +* pulls the API data into Gatsby's node system +* allows the data to be queried with GraphQL + +Congratulations! + +## Where next? + +Your plugin has been adapted from Jason Lengstorf's [gatsby-source-pixabay plugin](https://www.npmjs.com/package/gatsby-source-pixabay). Check out [the source on GitHub](https://github.com/jlengstorf/gatsby-source-pixabay). + +Try adding new features to your plugin, for example - download images from Pixabay, improve error handling, add documentation or automated tests. + +Check out Gatsby's docs on [plugin authoring](/docs/plugin-authoring/) and [creating a source plugin](/docs/create-source-plugin). + +### A note on JavaScript versions + +In this tutorial you've written code in a version of JavaScript that's compatible with Node.js version 6 and above. + +Jason's version of [the plugin](https://github.com/jlengstorf/gatsby-source-pixabay/blob/master/src/gatsby-node.js) uses newer JavaScript features with [babel](https://babeljs.io/) to provide compatibility for older versions of Node. Compare your code with Jason's to see how newer JavaScript features allow for more succinct code. diff --git a/docs/docs/wordpress-source-plugin-tutorial.md b/docs/docs/wordpress-source-plugin-tutorial.md new file mode 100644 index 0000000000000..43e4b610e336b --- /dev/null +++ b/docs/docs/wordpress-source-plugin-tutorial.md @@ -0,0 +1,154 @@ +## How to create a site with data pulled from WordPress + +### What this tutorial covers: + +In this tutorial, you will install the `gatsby-source-wordpress` plugin in order to pull blog and image data from a WordPress install into your Gatsby site and render that data. This [Gatsby + Wordpress demo site](https://using-wordpress.gatsbyjs.org/) shows you a sample of what you’re going to be building in this tutorial., although it’s missing the cool images you’ll be adding :D + +### Why go through this tutorial? + +While each source plugin may operate differently from others, it’s worth going through this tutorial because you will almost definitely be using a source plugin in most Gatsby sites you build. This tutorial will walk you through the basics of connecting your Gatsby site to a CMS, pulling in data, and using React to render that data in beautiful ways on your site. + +If you’d like to look at the growing number source plugins available to you, search for “source” in the [Gatsby plugin library](/plugins/?=source). + +### Creating a site with the `gatsby-source-wordpress` plugin + +Create a new Gatsby project and change directories into the new project you just created: + +```shell +gatsby new wordpress-tutorial-site +cd wordpress-tutorial-site +``` + +Install the `gatsby-source-wordpress` plugin. For extra reading on the plugin’s features and examples of GraphQL queries not included in this tutorial, see the [`gatsby-source-wordpress` plugin’s READme file](/packages/gatsby-source-wordpress/?=wordpress). + +```shell +npm install --save gatsby-source-wordpress +``` + +Add the `gatsby-source-wordpress` plugin to `gatsby-config.js` using the following code, which you can also find in the [demo site’s source code](https://github.com/gatsbyjs/gatsby/blob/master/examples/using-wordpress/gatsby-config.js). + +```javascript{32-58} + module.exports = { + siteMetadata: { + title: 'Gatsby Wordpress Tutorial', + }, + plugins: [ + // https://public-api.wordpress.com/wp/v2/sites/gatsbyjsexamplewordpress.wordpress.com/pages/ + /* + * Gatsby's data processing layer begins with “source” + * plugins. Here the site sources its data from Wordpress. + */ + { + resolve: `gatsby-source-wordpress`, + options: { + /* + * The base URL of the Wordpress site without the trailingslash and the protocol. This is required. + * Example : 'gatsbyjswpexample.wordpress.com' or 'www.example-site.com' + */ + baseUrl: `dev-gatbsyjswp.pantheonsite.io`, + // The protocol. This can be http or https. + protocol: `http`, + // Indicates whether the site is hosted on wordpress.com. + // If false, then the asumption is made that the site is self hosted. + // If true, then the plugin will source its content on wordpress.com using the JSON REST API V2. + // If your site is hosted on wordpress.org, then set this to false. + hostingWPCOM: false, + // If useACF is true, then the source plugin will try to import the Wordpress ACF Plugin contents. + // This feature is untested for sites hosted on Wordpress.com + useACF: true, + }, + }, + ], +} +``` + +### Creating GraphQL queries that pull data from WordPress + +Now you are ready to create a GraphQL query to pull in some data from the WordPress site. You will create a query that pulls in the title of the blogposts, date they were posted, and blogpost content. + +Run: + +```shell +gatsby develop +``` + +Open localhost:8000 and localhost:8000/___graphql. + +This query will pull in the blogpost content from WordPress: + +```graphql +query { + allWordpressPage { + edges { + node { + id + title + excerpt + slug + date(formatString: "MMMM DD, YYYY") + } + } + } +} +``` + + +This query will pull in a sorted list of those blogposts: + +```graphql +{ + allWordpressPost(sort: { fields: [date] }) { + edges { + node { + title + excerpt + slug + } + } + } +} +``` + + +### Rendering the blogposts to `index.js` + +Here is what your `index.js` should look like: + +```jsx +import React from 'react' + +export default ({ data }) => { + console.log(data) + return ( +
+

My WordPress Blog

+

Posts

+ {data.allWordpressPost.edges.map(({ node }) => ( +
+

{node.title}

+
+
+ ))} +
+ ) +} + +export const pageQuery = graphql` + query MyFiles { + allWordpressPost(sort: { fields: [date] }) { + edges { + node { + title + excerpt + slug + } + } + } + } +` +``` + +[Note to editors: it would be useful to insert a screenshot of the final result here] + +### Create slugs for each blogpost and link to them from `index.js` +[Part 7](/tutorial/part-seven/) of the foundational tutorial goes through this process. diff --git a/docs/docs/working-with-images.md b/docs/docs/working-with-images.md new file mode 100644 index 0000000000000..28d94522e08e5 --- /dev/null +++ b/docs/docs/working-with-images.md @@ -0,0 +1,99 @@ +--- +title: Working With Images In Gatsby +--- + +Optimizing images is a challenge on any website. To utilize best practices for performance across devices, you need multiple sizes and resolutions of each image. Luckily, Gatsby has several useful [plugins](/docs/plugins/) that work together to do that for images on [page components](/docs/building-with-components/#page-components). + + +The recommended approach is to use [GraphQL queries](/docs/querying-with-graphql/) to get images of the optimal size or resolution, then, display them with the [`gatsby-image`](/packages/gatsby-image/) component. + + +## Query Images With GraphQL + +Querying images with GraphQL allows you to access the image's data as well as perform transformations with [Sharp](https://github.com/lovell/sharp), a high-performance image processing library. + +You'll need a few plugins for this: +* [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) plugin allows you to [query files with GraphQL](docs/querying-with-graphql/#images) +* [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp) powers the connections between Sharp and Gatsby Plugins +* [`gatsby-transformer-sharp`](/packages/gatsby-transformer-sharp/) allows you to create multiples images of the right sizes and resolutions with a query + +If the final image is of a fixed size, optimization relies on having multiple resolutions of the image. If it is responsive, that is it stretches to fill a container or page, optimization relies on having different sizes of the same image. See the [Gatsby Image documentation for more information](/packages/gatsby-image/#two-types-of-responsive-images). + +You can also use arguments in your query to specify exact, minimum, and maximum dimensions. See the [Gatsby Image documentation for complete options](/packages/gatsby-image/#two-types-of-responsive-images). + +This example is for an image gallery where images stretch when the page is resized. It uses the `sizes` method and the size fragment to grab the right data to use in `gatsby-image` component and arguments to set the maximum width as 400px and maximum height as 250px. +```jsx +export const query = graphql` + query indexQuery { + fileName:file(relativePath: { eq: "images/myimage.jpg" }) { + childImageSharp { + sizes(maxWidth: 400, maxHeight: 250) { + ...GatsbyImageSharpSizes + } + } + } + } +`; +``` + +## Optimizing Images With Gatsby Image + +[`gatsby-image`](/packages/gatsby-image/) is a plugin that automatically creates React components for optimized images that: + + +> * Loads the optimal size of image for each device size and screen resolution +> * Holds the image position while loading so your page doesn't jump around as images load +> * Uses the "blur-up" effect i.e. it loads a tiny version of the image to show while the full image is loading +> * Alternatively provides a "traced placeholder" SVG of the image +> * Lazy loads images, which reduces bandwidth and speeds the initial load time +> * Uses [WebP](https://developers.google.com/speed/webp/) images, if browser supports the format + + +Here is an image component that uses the query from the previous example: + +``` + +``` + + +## Using Fragments To Standardize Formatting + +What if you have a bunch of images and you want them all to use the same formatting? + +A custom fragment is an easy way to standardize formatting and re-use it on multiple images: + +``` +export const squareImage = graphql` +fragment squareImage on File { + childImageSharp { + sizes(maxWidth: 200, maxHeight: 200) { + ...GatsbyImageSharpSizes + } + } +} +`; +``` + +The fragment can then be referenced in the image query: + +``` + +export const query = graphql` + query imageGallery { + image1:file(relativePath: { eq: "images/image1.jpg" }) { + ...squareImage + } + + image2:file(relativePath: { eq: "images/image2.jpg" }) { + ...squareImage + } + + image3:file(relativePath: { eq: "images/image3.jpg" }) { + ...squareImage + } + } +`; + +``` + + diff --git a/docs/tutorial/part-two/index.md b/docs/tutorial/part-two/index.md index 6ed3ea4ed18c0..f842907e469c8 100644 --- a/docs/tutorial/part-two/index.md +++ b/docs/tutorial/part-two/index.md @@ -336,7 +336,7 @@ Quoting from > A **CSS Module** is a CSS file in which all class names and animation names > are scoped locally by default. -CSS Modules is very popular as it lets you write CSS like normal but with +CSS Modules are very popular as they let you write CSS like normal but with a lot more safety. The tool automatically makes class and animation names unique so you don't have to worry about selector name collisions. diff --git a/examples/client-only-paths/.eslintrc b/examples/client-only-paths/.eslintrc.json similarity index 100% rename from examples/client-only-paths/.eslintrc rename to examples/client-only-paths/.eslintrc.json diff --git a/examples/feed/.eslintrc b/examples/feed/.eslintrc.json similarity index 100% rename from examples/feed/.eslintrc rename to examples/feed/.eslintrc.json diff --git a/examples/gatsbygram/.eslintrc b/examples/gatsbygram/.eslintrc.json similarity index 100% rename from examples/gatsbygram/.eslintrc rename to examples/gatsbygram/.eslintrc.json diff --git a/examples/hn/.eslintrc b/examples/hn/.eslintrc.json similarity index 100% rename from examples/hn/.eslintrc rename to examples/hn/.eslintrc.json diff --git a/examples/image-processing/src/pages/index.js b/examples/image-processing/src/pages/index.js index 8bca954f5274f..05b5392daec2c 100644 --- a/examples/image-processing/src/pages/index.js +++ b/examples/image-processing/src/pages/index.js @@ -6,17 +6,18 @@ import { rhythm } from "../utils/typography" class Index extends React.Component { render() { const images = this.props.data.allImageSharp.edges - const sizes = this.props.data.sizes.sizes - const resolutions = this.props.data.resolution.resolutions - const cropDefault = this.props.data.cropDefault.resize - const cropBottomLeft = this.props.data.cropBottomLeft.resize - const cropEntropy = this.props.data.cropEntropy.resize - const cropCenter = this.props.data.cropCenter.resize - const sizesDuotoneOriginal = this.props.data.sizesDuotoneOriginal.sizes - const sizesDuotone25 = this.props.data.sizesDuotone25.sizes - const sizesDuotone50 = this.props.data.sizesDuotone50.sizes - const sizesDuotone75 = this.props.data.sizesDuotone75.sizes - const sizesDuotone = this.props.data.sizesDuotone.sizes + const sizes = this.props.data.sizes.childImageSharp.sizes + const resolutions = this.props.data.resolution.childImageSharp.resolutions + const cropDefault = this.props.data.cropDefault.childImageSharp.resize + const cropBottomLeft = this.props.data.cropBottomLeft.childImageSharp.resize + const cropEntropy = this.props.data.cropEntropy.childImageSharp.resize + const cropCenter = this.props.data.cropCenter.childImageSharp.resize + const sizesDuotoneOriginal = this.props.data.sizesDuotoneOriginal + .childImageSharp.sizes + const sizesDuotone25 = this.props.data.sizesDuotone25.childImageSharp.sizes + const sizesDuotone50 = this.props.data.sizesDuotone50.childImageSharp.sizes + const sizesDuotone75 = this.props.data.sizesDuotone75.childImageSharp.sizes + const sizesDuotone = this.props.data.sizesDuotone.childImageSharp.sizes return (
@@ -44,7 +45,12 @@ class Index extends React.Component { documentation {` `} - or peep the code of this example site for more information. + or peep the{` `} + + code + + {` `} + of this example site for more information.

@@ -359,91 +365,115 @@ export const pageQuery = graphql` } } } - sizes: imageSharp(id: { regex: "/fecolormatrix-kanye-west.jpg/" }) { - sizes( - duotone: { highlight: "#f00e2e", shadow: "#192550" } - traceSVG: { - color: "#f00e2e" - turnPolicy: TURNPOLICY_MINORITY - blackOnWhite: false + sizes: file(relativePath: { regex: "/fecolormatrix-kanye-west.jpg/" }) { + childImageSharp { + sizes( + duotone: { highlight: "#f00e2e", shadow: "#192550" } + traceSVG: { + color: "#f00e2e" + turnPolicy: TURNPOLICY_MINORITY + blackOnWhite: false + } + toFormat: PNG + ) { + ...GatsbyImageSharpSizes_tracedSVG } - toFormat: PNG - ) { - ...GatsbyImageSharpSizes_tracedSVG } } - sizesDuotone: imageSharp(id: { regex: "/fecolormatrix-kanye-west.jpg/" }) { - sizes( - maxWidth: 120 - duotone: { highlight: "#0ec4f1", shadow: "#192550" } - traceSVG: { color: "#1E2151" } - ) { - ...GatsbyImageSharpSizes_tracedSVG + sizesDuotone: file( + relativePath: { regex: "/fecolormatrix-kanye-west.jpg/" } + ) { + childImageSharp { + sizes( + maxWidth: 120 + duotone: { highlight: "#0ec4f1", shadow: "#192550" } + traceSVG: { color: "#1E2151" } + ) { + ...GatsbyImageSharpSizes_tracedSVG + } } } - sizesDuotone50: imageSharp( - id: { regex: "/fecolormatrix-kanye-west.jpg/" } + sizesDuotone50: file( + relativePath: { regex: "/fecolormatrix-kanye-west.jpg/" } ) { - sizes( - maxWidth: 120 - duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 50 } - traceSVG: { color: "#A7DEF6" } - ) { - ...GatsbyImageSharpSizes_tracedSVG + childImageSharp { + sizes( + maxWidth: 120 + duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 50 } + traceSVG: { color: "#A7DEF6" } + ) { + ...GatsbyImageSharpSizes_tracedSVG + } } } - sizesDuotone75: imageSharp( - id: { regex: "/fecolormatrix-kanye-west.jpg/" } + sizesDuotone75: file( + relativePath: { regex: "/fecolormatrix-kanye-west.jpg/" } ) { - sizes( - maxWidth: 120 - duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 75 } - traceSVG: { color: "#0ec4f1" } - ) { - ...GatsbyImageSharpSizes_tracedSVG + childImageSharp { + sizes( + maxWidth: 120 + duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 75 } + traceSVG: { color: "#0ec4f1" } + ) { + ...GatsbyImageSharpSizes_tracedSVG + } } } - sizesDuotone25: imageSharp( - id: { regex: "/fecolormatrix-kanye-west.jpg/" } + sizesDuotone25: file( + relativePath: { regex: "/fecolormatrix-kanye-west.jpg/" } ) { - sizes( - maxWidth: 120 - traceSVG: { color: "#D1EFFB" } - duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 25 } - ) { - ...GatsbyImageSharpSizes_tracedSVG + childImageSharp { + sizes( + maxWidth: 120 + traceSVG: { color: "#D1EFFB" } + duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 25 } + ) { + ...GatsbyImageSharpSizes_tracedSVG + } } } - sizesDuotoneOriginal: imageSharp( - id: { regex: "/fecolormatrix-kanye-west.jpg/" } + sizesDuotoneOriginal: file( + relativePath: { regex: "/fecolormatrix-kanye-west.jpg/" } ) { - sizes(maxWidth: 120, traceSVG: { color: "#e7f7fe" }, toFormat: PNG) { - ...GatsbyImageSharpSizes_tracedSVG + childImageSharp { + sizes(maxWidth: 120, traceSVG: { color: "#e7f7fe" }, toFormat: PNG) { + ...GatsbyImageSharpSizes_tracedSVG + } } } - resolution: imageSharp(id: { regex: "/lol.jpg/" }) { - resolutions(grayscale: true, width: 500) { - ...GatsbyImageSharpResolutions_withWebp + resolution: file(relativePath: { regex: "/lol.jpg/" }) { + childImageSharp { + resolutions(grayscale: true, width: 500) { + ...GatsbyImageSharpResolutions_withWebp + } } } - cropDefault: imageSharp(id: { regex: "/gatsby.jpg/" }) { - resize(width: 180, height: 180) { - src + cropDefault: file(relativePath: { regex: "/gatsby.jpg/" }) { + childImageSharp { + resize(width: 180, height: 180) { + src + } } } - cropBottomLeft: imageSharp(id: { regex: "/nyancat/" }) { - resize(width: 180, height: 180, cropFocus: SOUTHWEST) { - src + cropBottomLeft: file(relativePath: { regex: "/nyancat/" }) { + childImageSharp { + resize(width: 180, height: 180, cropFocus: SOUTHWEST) { + src + } } } - cropEntropy: imageSharp(id: { regex: "/gatsby.jpg/" }) { - resize(width: 180, height: 180, cropFocus: ENTROPY) { - src + cropEntropy: file(relativePath: { regex: "/gatsby.jpg/" }) { + childImageSharp { + resize(width: 180, height: 180, cropFocus: ENTROPY) { + src + } } } - cropCenter: imageSharp(id: { regex: "/gatsby.jpg/" }) { - resize(width: 180, height: 180, cropFocus: CENTER) { - src + cropCenter: file(relativePath: { regex: "/gatsby.jpg/" }) { + childImageSharp { + resize(width: 180, height: 180, cropFocus: CENTER) { + src + } } } } diff --git a/examples/no-plugins/.eslintrc b/examples/no-plugins/.eslintrc.json similarity index 100% rename from examples/no-plugins/.eslintrc rename to examples/no-plugins/.eslintrc.json diff --git a/examples/no-trailing-slashes/.eslintrc b/examples/no-trailing-slashes/.eslintrc.json similarity index 100% rename from examples/no-trailing-slashes/.eslintrc rename to examples/no-trailing-slashes/.eslintrc.json diff --git a/examples/styleguide/.eslintrc b/examples/styleguide/.eslintrc.json similarity index 100% rename from examples/styleguide/.eslintrc rename to examples/styleguide/.eslintrc.json diff --git a/examples/using-contentful/.eslintrc b/examples/using-contentful/.eslintrc.json similarity index 100% rename from examples/using-contentful/.eslintrc rename to examples/using-contentful/.eslintrc.json diff --git a/examples/using-contentful/package.json b/examples/using-contentful/package.json index e54f7e719ac10..20f3026dde723 100644 --- a/examples/using-contentful/package.json +++ b/examples/using-contentful/package.json @@ -25,6 +25,9 @@ ], "license": "MIT", "main": "n/a", + "resolutions": { + "contentful": "6.1.0" + }, "scripts": { "develop": "gatsby develop", "build": "gatsby build", diff --git a/examples/using-css-modules/.eslintrc b/examples/using-css-modules/.eslintrc.json similarity index 100% rename from examples/using-css-modules/.eslintrc rename to examples/using-css-modules/.eslintrc.json diff --git a/examples/using-csv/.eslintrc b/examples/using-csv/.eslintrc.json similarity index 100% rename from examples/using-csv/.eslintrc rename to examples/using-csv/.eslintrc.json diff --git a/examples/using-drupal/.eslintrc b/examples/using-drupal/.eslintrc.json similarity index 100% rename from examples/using-drupal/.eslintrc rename to examples/using-drupal/.eslintrc.json diff --git a/examples/using-emotion-prismjs/.eslintrc b/examples/using-emotion-prismjs/.eslintrc.json similarity index 100% rename from examples/using-emotion-prismjs/.eslintrc rename to examples/using-emotion-prismjs/.eslintrc.json diff --git a/examples/using-emotion/.eslintrc b/examples/using-emotion/.eslintrc.json similarity index 100% rename from examples/using-emotion/.eslintrc rename to examples/using-emotion/.eslintrc.json diff --git a/examples/using-excel/.eslintrc b/examples/using-excel/.eslintrc.json similarity index 100% rename from examples/using-excel/.eslintrc rename to examples/using-excel/.eslintrc.json diff --git a/examples/using-gatsby-image/.eslintrc b/examples/using-gatsby-image/.eslintrc.json similarity index 100% rename from examples/using-gatsby-image/.eslintrc rename to examples/using-gatsby-image/.eslintrc.json diff --git a/examples/using-gatsby-image/README.md b/examples/using-gatsby-image/README.md index 5cdc61815efa8..1e69e0f5f2114 100644 --- a/examples/using-gatsby-image/README.md +++ b/examples/using-gatsby-image/README.md @@ -1,5 +1,5 @@ -# using-gatsby-image +# Using Gatsby Image https://using-gatsby-image.gatsbyjs.org -Stub README description +Gatsby example site that shows how to use the [gatsby-image](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-image) plugin. diff --git a/examples/using-glamor/.eslintrc b/examples/using-glamor/.eslintrc.json similarity index 100% rename from examples/using-glamor/.eslintrc rename to examples/using-glamor/.eslintrc.json diff --git a/examples/using-hjson/.eslintrc b/examples/using-hjson/.eslintrc.json similarity index 100% rename from examples/using-hjson/.eslintrc rename to examples/using-hjson/.eslintrc.json diff --git a/examples/using-medium/.eslintrc b/examples/using-medium/.eslintrc.json similarity index 100% rename from examples/using-medium/.eslintrc rename to examples/using-medium/.eslintrc.json diff --git a/examples/using-mongodb/.eslintrc b/examples/using-mongodb/.eslintrc.json similarity index 100% rename from examples/using-mongodb/.eslintrc rename to examples/using-mongodb/.eslintrc.json diff --git a/examples/using-page-loading-indicator/.eslintrc b/examples/using-page-loading-indicator/.eslintrc.json similarity index 100% rename from examples/using-page-loading-indicator/.eslintrc rename to examples/using-page-loading-indicator/.eslintrc.json diff --git a/examples/using-path-prefix/.eslintrc b/examples/using-path-prefix/.eslintrc.json similarity index 100% rename from examples/using-path-prefix/.eslintrc rename to examples/using-path-prefix/.eslintrc.json diff --git a/examples/using-react-native-web/.eslintrc b/examples/using-react-native-web/.eslintrc.json similarity index 100% rename from examples/using-react-native-web/.eslintrc rename to examples/using-react-native-web/.eslintrc.json diff --git a/examples/using-react-native-web/README.md b/examples/using-react-native-web/README.md index 37be72a12efb4..ebe4a0b91c2f5 100644 --- a/examples/using-react-native-web/README.md +++ b/examples/using-react-native-web/README.md @@ -4,3 +4,8 @@ The example shows how to use [gatsby-plugin-react-native-web](https://github.com/slorber/gatsby-plugin-react-native-web) This permits to use React Native UI View components inside a Gatsby Storybook, and thus share same UI code between web and mobile. + + +Check the [Online demo](https://gatsby-rnw.now.sh/) + +![online demo screenshot](https://pbs.twimg.com/media/Db4PTPKW0AAVPl8.jpg) diff --git a/examples/using-react-native-web/package.json b/examples/using-react-native-web/package.json index b1348f0ff930b..8b03674f95f53 100644 --- a/examples/using-react-native-web/package.json +++ b/examples/using-react-native-web/package.json @@ -4,17 +4,18 @@ "description": "Example usage of gatsby-plugin-react-native-web", "author": "Sebastien Lorber ", "dependencies": { - "gatsby": "^1.9.221", - "gatsby-link": "^1.6.37", - "gatsby-plugin-google-analytics": "latest", - "gatsby-plugin-react-native-web": "^0.1.2", + "gatsby": "^1.9.255", + "gatsby-link": "^1.6.41", + "gatsby-plugin-google-analytics": "1.0.31", + "gatsby-plugin-react-native-web": "^0.3.0", "gatsby-plugin-react-next": "^1.0.11", - "react": "^16.2.0", - "react-dom": "^16.2.0", - "react-native-web": "^0.5.1" + "react": "^16.3.2", + "react-art": "^16.3.2", + "react-dom": "^16.3.2", + "react-native-web": "^0.6.1" }, "devDependencies": { - "babel-plugin-react-native-web": "^0.5.1" + "babel-plugin-react-native-web": "^0.6.1" }, "license": "MIT", "scripts": { diff --git a/examples/using-react-native-web/src/pages/index.js b/examples/using-react-native-web/src/pages/index.js index 59b278f9cae85..d30ebef5c1b99 100644 --- a/examples/using-react-native-web/src/pages/index.js +++ b/examples/using-react-native-web/src/pages/index.js @@ -6,33 +6,214 @@ import { Switch, Button, ActivityIndicator, + CheckBox, + Picker, + ProgressBar, + Linking, + Animated, + TouchableOpacity, } from "react-native" +import GatsbyLink from "gatsby-link" + const styles = StyleSheet.create({ container: { - padding: 10, + padding: 20, + }, + header: { + fontSize: 38, + }, + headerSub: { + marginTop: 10, + fontSize: 18, + }, + openLinkButton: { + margin: 10, + maxWidth: 400, + }, + row: { + flexDirection: `row`, + alignItems: `center`, }, }) -const Container = props => ( - +const Container = ({ style, ...props }) => ( + +) + +const Header = ({ children }) => ( + {children} ) +const HeaderSub = ({ style, children }) => ( + {children} +) + +const OpenLinkButton = ({ title, url }) => ( + +