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/CONTRIBUTING.md b/CONTRIBUTING.md index b6333bf7a62a1..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 `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. - -### 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..a8dfe05367eaf 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/) @@ -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,15 @@ 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)) ## 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/author.yaml b/docs/blog/author.yaml index bdb1505f5565e..c0a68d21515f5 100644 --- a/docs/blog/author.yaml +++ b/docs/blog/author.yaml @@ -117,6 +117,10 @@ 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 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/docs/awesome-gatsby.md b/docs/docs/awesome-gatsby.md index c7c97e5e0cda6..e0c41a51aafba 100644 --- a/docs/docs/awesome-gatsby.md +++ b/docs/docs/awesome-gatsby.md @@ -22,6 +22,7 @@ See the [list of official and community plugins](/docs/plugins/) ## Podcasts +* [2018-04-17 Gatsby.js w/Jason Lengstorf](https://spec.fm/podcasts/toolsday/134337) * [2018-02-28 syntax.fm on Static Site Generators (lots of Gatsby love)](https://syntax.fm/show/034/why-static-site-generators-are-awesome) * [2017-09-21 Kyle Mathews on JAMSTACK radio on "Static Site Generation with GatsbyJS](https://www.heavybit.com/library/podcasts/jamstack-radio/ep-22-static-site-generation-with-gatsbyjs/) * [2017-07-21 Kyle Mathews on Web of Tomorrow](https://www.orbit.fm/weboftomorrow/39/) diff --git a/docs/docs/deploy-gatsby.md b/docs/docs/deploy-gatsby.md index 6531b0fbcd8c8..804f0d976b42e 100644 --- a/docs/docs/deploy-gatsby.md +++ b/docs/docs/deploy-gatsby.md @@ -151,9 +151,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 8b0a80623406c..90f930c699072 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: diff --git a/docs/docs/gatsby-style-guide.md b/docs/docs/gatsby-style-guide.md index f731fbc3c9e64..36e4ad722fc23 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..e0d7b2f540382 --- /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 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! diff --git a/docs/docs/image-tutorial.md b/docs/docs/image-tutorial.md new file mode 100644 index 0000000000000..a99e9eb3e09f9 --- /dev/null +++ b/docs/docs/image-tutorial.md @@ -0,0 +1,269 @@ +## 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 gatsby-source-filesystem +``` + +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', + { + resolve: `gatsby-source-filesystem`, + options: { + name: `images`, + path: `${__dirname}/src/images/`, + }, + }, + ], +} +``` + +### 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/wordpress-source-plugin-tutorial.md b/docs/docs/wordpress-source-plugin-tutorial.md new file mode 100644 index 0000000000000..8f2350b46205d --- /dev/null +++ b/docs/docs/wordpress-source-plugin-tutorial.md @@ -0,0 +1,156 @@ +## 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 + ...PostIcons + } + } + } +} +``` + + +### 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}

+

{node.excerpt}

+
+ ))} +
+ )T +} + +// Set here the ID of the home page. +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/tutorial/part-two/index.md b/docs/tutorial/part-two/index.md index 2eac1d1bbcb4c..9017a1c82d629 100644 --- a/docs/tutorial/part-two/index.md +++ b/docs/tutorial/part-two/index.md @@ -347,9 +347,7 @@ Gatsby works out of the box with CSS Modules. Let's build a page using CSS Modules. First, let's create a new `Container` component which we'll use for each of the -CSS-in-JS examples. Create a `components` directory at `src/components` and -then, in this directory, create a file named `container.js` and paste the -following: +CSS-in-JS examples. Create a new directory at `src/components` and then, in this new directory, create a file named `container.js` and paste the following: ```javascript import React from "react"; 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 6cea3da053c5c..e69240f912c5e 100644 --- a/examples/using-contentful/package.json +++ b/examples/using-contentful/package.json @@ -23,6 +23,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 }) => ( + +