From 6f51055aa9e2d4b21d4d18e9807686dadbe9c0fc Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Tue, 2 Apr 2019 16:13:42 -0700 Subject: [PATCH 1/6] docs: add page on creating starters --- docs/contributing/create-a-starter.md | 73 ++++++++++++++++++- docs/docs/starters.md | 2 + www/src/data/sidebars/contributing-links.yaml | 2 + www/src/data/sidebars/doc-links.yaml | 3 - 4 files changed, 73 insertions(+), 7 deletions(-) diff --git a/docs/contributing/create-a-starter.md b/docs/contributing/create-a-starter.md index 8bb711c365ab7..c6a34f46bd488 100644 --- a/docs/contributing/create-a-starter.md +++ b/docs/contributing/create-a-starter.md @@ -1,9 +1,74 @@ --- title: Create a Starter -issue: https://github.com/gatsbyjs/gatsby/issues/8103 --- -This is a stub. Help our community expand it. +[Starters](/docs/starters/) are boilerplate projects that Gatsby developers can use to set up a new site quickly. -Please use the [Gatsby Style Guide](/contributing/gatsby-style-guide/) to ensure your -pull request gets accepted. +When creating a starter, it needs to include some basic files (see the [Hello World starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/) for a barebones example): + +- `README.md`: instructions for how to install and configure your starter, a list of its features or structure, and any helpful tips. +- `package.json`: the "command center" for Gatsby dependencies and scripts. Find an example in the [Hello World Starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/package.json). +- `gatsby-config.js`: a space to add configurable data and plugins. See [Gatsby Config](/docs/gatsby-config/) for more information. +- `src/pages`: a directory for page components to live, with at least [one example](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/src/pages/index.js). +- `static`: a directory for static assets, such as a `favicon.ico` file. +- `.gitignore` *(optional)*: a file telling Git which resources to leave out of source control, such as the `node_modules` directory, log files, Gatsby `.cache` and `public` directories. +- `.prettierrc` *(optional)*: a configuration file for [Prettier](https://prettier.io/), a JavaScript linter and formatter used for Gatsby development. + +Your starter should also have these qualities: + +- Open source and available from a stable URL +- Configurable +- Fast +- Web accessible + +Let's expand upon these items to prepare you for creating a winning starter. + +## Open source and available from a stable URL + +The Gatsby CLI allows users to install a new site with a starter using the command `gatsby new `. For this to work, your starter needs to be available to download. The easiest way to accomplish this is to host your starter on GitHub or Gitlab and use the publicly available repo URL, such as: + +```shell +gatsby new https://github.com/gatsbyjs/gatsby-starter-blog +``` + +Although the official starters live in the Gatsby repo, community members can offer their own starters from their own repos. Here's an example of installing a community starter: +```shell +gatsby new https://github.com/netlify-templates/gatsby-starter-netlify-cms +``` + +## Configurable + +Starters should utilize metadata in `gatsby-config.js` wherever possible, as this is typically the first place users will look for site configuration information. Some examples of things you could make configurable in `gatsby-config` include: + +- Site title +- Basic color palette +- Author name, contact information, and bio + +Alternatively, for starters connecting to a headless CMS, author-specific items could be pulled in tp the starter from a CMS platform using a source plugin and GraphQL instead. Showing users how this is done can make your starter very helpful! + +## Fast + +Gatsby is pretty darned fast out of the box. To make a starter that supports users in the "Gatsby way", you'll want to set up a test implementation with your starter for debugging performance. Using tools like [Lighthouse](https://developers.google.com/web/tools/lighthouse/) and [Webpagetest.org](https://www.webpagetest.org/), you can evaluate the speed of your test site and make any necessary improvements to the starter source code so your users will benefit from fast defaults. + +If there are areas of the starter that could be impacted by the user, it may help to add some documentation or code comments reminding them to optimize for performance (e.g. compressing images)! + +## Web accessible + +In addition to performance, creating a starter free of accessibility issues is a wonderful way to contribute to the Gatsby ecosystem. Here are some tips for creating an inclusive, accessible starter: + +- Use adequate [color contrast](https://webaim.org/articles/contrast/). (This is the most common accessibility issue on the web!) +- Preserve [visible keyboard focus indicators](https://webaim.org/techniques/keyboard/). +- Use [image alt text](https://webaim.org/techniques/alttext/) in your examples. +- Recommend and use [semantic HTML](https://webaim.org/techniques/semanticstructure/) wherever possible. +- [Label your form inputs](https://webaim.org/techniques/forms/). + +For more accessibility help, check out the [A11y Project checklist](https://a11yproject.com/checklist) and [WebAIM](https://webaim.org). You can also check out [tips on creating accessible web apps](https://www.deque.com/blog/accessibility-tips-in-single-page-applications/) heavy on client-side JavaScript. + +## Add your starter to the Gatsby Starter Library + +To make sure your starter is easily discoverable, don't forget to add it to the [Gatsby Starter Library](/contributing/submit-to-starter-library/). Add tags to your starter by first checking for existing ones (like `contentful`, `csv`, etc.), and adding more if needed! + +## Further reading: + +- [How to create a Gatsby Starter +](https://medium.com/@emasuriano/how-to-create-a-gatsby-starter-e7d53083a880) by Emanuel Suriano diff --git a/docs/docs/starters.md b/docs/docs/starters.md index 0b58c7b912f01..9e278e9231d4c 100644 --- a/docs/docs/starters.md +++ b/docs/docs/starters.md @@ -33,6 +33,8 @@ Official starters are maintained by Gatsby. Community starters are created and maintained by Gatsby community members. +> Learn [how to make a starter](/contributing/create-a-starter/) in the Gatsby contributing docs. + Looking for a starter for a particular use case? Peruse starters that have been submitted to the [Starter Library](/starters/) Created a starter you'd like to share? Follow [these steps to submit your starter](/contributing/submit-to-starter-library/) to the Starter Library. diff --git a/www/src/data/sidebars/contributing-links.yaml b/www/src/data/sidebars/contributing-links.yaml index e47616c54eb9f..d3a874c966bf3 100644 --- a/www/src/data/sidebars/contributing-links.yaml +++ b/www/src/data/sidebars/contributing-links.yaml @@ -47,6 +47,8 @@ link: /contributing/code-contributions/ - title: Setting Up Your Local Dev Environment link: /contributing/setting-up-your-local-dev-environment/ + - title: Create a Starter + link: /contributing/create-a-starter/ - title: Community Contributions link: /contributing/community-contributions/ items: diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 97773ce86abc4..ca46dea5fb9a7 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -154,9 +154,6 @@ link: /docs/source-plugin-tutorial/ - title: Starters link: /docs/starters/ - items: - - title: Create a Starter* - link: /contributing/create-a-starter/ - title: Styling Your Site link: /docs/styling/ items: From bafe385f6c7d2c21be5e8394e700b3d8a2d71b2b Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Tue, 2 Apr 2019 16:22:07 -0700 Subject: [PATCH 2/6] linter output, formatting, and a few more links --- docs/contributing/create-a-starter.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/contributing/create-a-starter.md b/docs/contributing/create-a-starter.md index c6a34f46bd488..5224ee9037251 100644 --- a/docs/contributing/create-a-starter.md +++ b/docs/contributing/create-a-starter.md @@ -2,17 +2,19 @@ title: Create a Starter --- -[Starters](/docs/starters/) are boilerplate projects that Gatsby developers can use to set up a new site quickly. +[Starters](/docs/starters/) are boilerplate projects that Gatsby developers can use to set up a new site quickly. Before creating a starter, it may be helpful to peruse the [Gatsby Starter Library](/starters/) to see what already exists and determine how your starter will provide value. -When creating a starter, it needs to include some basic files (see the [Hello World starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/) for a barebones example): +## Basic requirements + +For a starter to work properly, it needs to include some files (see the [Hello World starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/) for a barebones example): - `README.md`: instructions for how to install and configure your starter, a list of its features or structure, and any helpful tips. - `package.json`: the "command center" for Gatsby dependencies and scripts. Find an example in the [Hello World Starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/package.json). - `gatsby-config.js`: a space to add configurable data and plugins. See [Gatsby Config](/docs/gatsby-config/) for more information. - `src/pages`: a directory for page components to live, with at least [one example](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/src/pages/index.js). - `static`: a directory for static assets, such as a `favicon.ico` file. -- `.gitignore` *(optional)*: a file telling Git which resources to leave out of source control, such as the `node_modules` directory, log files, Gatsby `.cache` and `public` directories. -- `.prettierrc` *(optional)*: a configuration file for [Prettier](https://prettier.io/), a JavaScript linter and formatter used for Gatsby development. +- `.gitignore` _(optional)_: a file telling Git which resources to leave out of source control, such as the `node_modules` directory, log files, Gatsby `.cache` and `public` directories. +- `.prettierrc` _(optional)_: a configuration file for [Prettier](https://prettier.io/), a JavaScript linter and formatter used for Gatsby development. Your starter should also have these qualities: @@ -27,14 +29,11 @@ Let's expand upon these items to prepare you for creating a winning starter. The Gatsby CLI allows users to install a new site with a starter using the command `gatsby new `. For this to work, your starter needs to be available to download. The easiest way to accomplish this is to host your starter on GitHub or Gitlab and use the publicly available repo URL, such as: -```shell -gatsby new https://github.com/gatsbyjs/gatsby-starter-blog -``` +`gatsby new https://github.com/gatsbyjs/gatsby-starter-blog` Although the official starters live in the Gatsby repo, community members can offer their own starters from their own repos. Here's an example of installing a community starter: -```shell -gatsby new https://github.com/netlify-templates/gatsby-starter-netlify-cms -``` + +`gatsby new https://github.com/netlify-templates/gatsby-starter-netlify-cms` ## Configurable @@ -71,4 +70,5 @@ To make sure your starter is easily discoverable, don't forget to add it to the ## Further reading: - [How to create a Gatsby Starter -](https://medium.com/@emasuriano/how-to-create-a-gatsby-starter-e7d53083a880) by Emanuel Suriano + ](https://medium.com/@emasuriano/how-to-create-a-gatsby-starter-e7d53083a880) by Emanuel Suriano +- [Introducing Gatsby Themes](https://www.gatsbyjs.org/blog/2018-11-11-introducing-gatsby-themes/) (including info on starters) From 8dc86ea2e5efce07302108c40b5660c9954b9994 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 3 Apr 2019 18:16:09 -0700 Subject: [PATCH 3/6] incorporate feedback --- docs/contributing/create-a-starter.md | 10 +++++----- docs/docs/starters.md | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/contributing/create-a-starter.md b/docs/contributing/create-a-starter.md index 5224ee9037251..bf0f2a09d9070 100644 --- a/docs/contributing/create-a-starter.md +++ b/docs/contributing/create-a-starter.md @@ -9,11 +9,11 @@ title: Create a Starter For a starter to work properly, it needs to include some files (see the [Hello World starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/) for a barebones example): - `README.md`: instructions for how to install and configure your starter, a list of its features or structure, and any helpful tips. -- `package.json`: the "command center" for Gatsby dependencies and scripts. Find an example in the [Hello World Starter](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/package.json). +- `package.json`: the "command center" for Gatsby dependencies and scripts. Find an example in the [Hello World starter's package.json](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/package.json) file. - `gatsby-config.js`: a space to add configurable data and plugins. See [Gatsby Config](/docs/gatsby-config/) for more information. -- `src/pages`: a directory for page components to live, with at least [one example](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/src/pages/index.js). +- `src/pages`: a directory for page components to live, with at least one [index.js file (example)](https://github.com/gatsbyjs/gatsby-starter-hello-world/blob/master/src/pages/index.js). - `static`: a directory for static assets, such as a `favicon.ico` file. -- `.gitignore` _(optional)_: a file telling Git which resources to leave out of source control, such as the `node_modules` directory, log files, Gatsby `.cache` and `public` directories. +- `.gitignore`: a file telling Git which resources to leave out of source control, such as the `node_modules` directory, log files, Gatsby `.cache` and `public` directories. - `.prettierrc` _(optional)_: a configuration file for [Prettier](https://prettier.io/), a JavaScript linter and formatter used for Gatsby development. Your starter should also have these qualities: @@ -43,7 +43,7 @@ Starters should utilize metadata in `gatsby-config.js` wherever possible, as thi - Basic color palette - Author name, contact information, and bio -Alternatively, for starters connecting to a headless CMS, author-specific items could be pulled in tp the starter from a CMS platform using a source plugin and GraphQL instead. Showing users how this is done can make your starter very helpful! +Alternatively, for starters connecting to a headless CMS, author-specific items could be pulled in to the starter from a CMS platform using a source plugin and GraphQL instead. Showing users how this is done can make your starter very helpful! ## Fast @@ -71,4 +71,4 @@ To make sure your starter is easily discoverable, don't forget to add it to the - [How to create a Gatsby Starter ](https://medium.com/@emasuriano/how-to-create-a-gatsby-starter-e7d53083a880) by Emanuel Suriano -- [Introducing Gatsby Themes](https://www.gatsbyjs.org/blog/2018-11-11-introducing-gatsby-themes/) (including info on starters) +- [Introducing Gatsby Themes](/blog/2018-11-11-introducing-gatsby-themes/) (including info on starters) diff --git a/docs/docs/starters.md b/docs/docs/starters.md index 9e278e9231d4c..74c433567e1d1 100644 --- a/docs/docs/starters.md +++ b/docs/docs/starters.md @@ -18,6 +18,8 @@ This downloads the files and initializes the site by running `npm install` If you don't specify a custom starter, your site will be created from the [default starter](https://github.com/gatsbyjs/gatsby-starter-default). +> Learn [how to make a starter](/contributing/create-a-starter/) in the Gatsby contributing docs. Starters can be created for your team(s) only, or distributed to the broader community. It's up to you! + ## Official starters Official starters are maintained by Gatsby. @@ -33,8 +35,6 @@ Official starters are maintained by Gatsby. Community starters are created and maintained by Gatsby community members. -> Learn [how to make a starter](/contributing/create-a-starter/) in the Gatsby contributing docs. - Looking for a starter for a particular use case? Peruse starters that have been submitted to the [Starter Library](/starters/) Created a starter you'd like to share? Follow [these steps to submit your starter](/contributing/submit-to-starter-library/) to the Starter Library. From a6849df8ee21b50321f6248ae64f1f7abfdf41e7 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 3 Apr 2019 18:24:51 -0700 Subject: [PATCH 4/6] add info about theming and configuration --- docs/contributing/create-a-starter.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/contributing/create-a-starter.md b/docs/contributing/create-a-starter.md index bf0f2a09d9070..749276915ee86 100644 --- a/docs/contributing/create-a-starter.md +++ b/docs/contributing/create-a-starter.md @@ -40,11 +40,13 @@ Although the official starters live in the Gatsby repo, community members can of Starters should utilize metadata in `gatsby-config.js` wherever possible, as this is typically the first place users will look for site configuration information. Some examples of things you could make configurable in `gatsby-config` include: - Site title -- Basic color palette - Author name, contact information, and bio +- Social media description Alternatively, for starters connecting to a headless CMS, author-specific items could be pulled in to the starter from a CMS platform using a source plugin and GraphQL instead. Showing users how this is done can make your starter very helpful! +It's also highly appreciated if the built-in theming capabilities are used and a "theme" file is exposed for configuration, for example when using styled-components or a design system. + ## Fast Gatsby is pretty darned fast out of the box. To make a starter that supports users in the "Gatsby way", you'll want to set up a test implementation with your starter for debugging performance. Using tools like [Lighthouse](https://developers.google.com/web/tools/lighthouse/) and [Webpagetest.org](https://www.webpagetest.org/), you can evaluate the speed of your test site and make any necessary improvements to the starter source code so your users will benefit from fast defaults. From 74129eca182506ca38c734cbf004cb8dfb6ef183 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Thu, 4 Apr 2019 11:19:31 -0700 Subject: [PATCH 5/6] move Create a Starter page back to docs --- .../create-a-starter.md => docs/creating-a-starter.md} | 2 +- docs/docs/starters.md | 2 +- www/src/data/sidebars/contributing-links.yaml | 2 -- www/src/data/sidebars/doc-links.yaml | 5 +++++ 4 files changed, 7 insertions(+), 4 deletions(-) rename docs/{contributing/create-a-starter.md => docs/creating-a-starter.md} (99%) diff --git a/docs/contributing/create-a-starter.md b/docs/docs/creating-a-starter.md similarity index 99% rename from docs/contributing/create-a-starter.md rename to docs/docs/creating-a-starter.md index 749276915ee86..5bda24b376156 100644 --- a/docs/contributing/create-a-starter.md +++ b/docs/docs/creating-a-starter.md @@ -1,5 +1,5 @@ --- -title: Create a Starter +title: Creating a Starter --- [Starters](/docs/starters/) are boilerplate projects that Gatsby developers can use to set up a new site quickly. Before creating a starter, it may be helpful to peruse the [Gatsby Starter Library](/starters/) to see what already exists and determine how your starter will provide value. diff --git a/docs/docs/starters.md b/docs/docs/starters.md index 74c433567e1d1..682803d0397bd 100644 --- a/docs/docs/starters.md +++ b/docs/docs/starters.md @@ -18,7 +18,7 @@ This downloads the files and initializes the site by running `npm install` If you don't specify a custom starter, your site will be created from the [default starter](https://github.com/gatsbyjs/gatsby-starter-default). -> Learn [how to make a starter](/contributing/create-a-starter/) in the Gatsby contributing docs. Starters can be created for your team(s) only, or distributed to the broader community. It's up to you! +> Learn [how to make a starter](/docs/creating-a-starter/) in the Gatsby docs. Starters can be created for your team(s) only, or distributed to the broader community. It's up to you! ## Official starters diff --git a/www/src/data/sidebars/contributing-links.yaml b/www/src/data/sidebars/contributing-links.yaml index 1eeee89f9eba8..0d42815d0109d 100644 --- a/www/src/data/sidebars/contributing-links.yaml +++ b/www/src/data/sidebars/contributing-links.yaml @@ -48,8 +48,6 @@ link: /contributing/code-contributions/ - title: Setting Up Your Local Dev Environment link: /contributing/setting-up-your-local-dev-environment/ - - title: Create a Starter - link: /contributing/create-a-starter/ - title: Community Contributions link: /contributing/community-contributions/ items: diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 6f8c3bdd7541b..0b6d75cccecb5 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -163,6 +163,11 @@ link: /plugins/ - title: Starters link: /docs/starters/ + items: + - title: Starter Library + link: /starters/ + - title: Creating a Starter + link: /docs/creating-a-starter/ - title: Styling Your Site link: /docs/styling/ items: From a6e5963a1d3773fe370378c7d08550a7872ce7bb Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Thu, 4 Apr 2019 14:28:33 -0700 Subject: [PATCH 6/6] soften language around adding to Starter Library --- docs/docs/creating-a-starter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/creating-a-starter.md b/docs/docs/creating-a-starter.md index 5bda24b376156..f21e2778c868f 100644 --- a/docs/docs/creating-a-starter.md +++ b/docs/docs/creating-a-starter.md @@ -67,7 +67,7 @@ For more accessibility help, check out the [A11y Project checklist](https://a11y ## Add your starter to the Gatsby Starter Library -To make sure your starter is easily discoverable, don't forget to add it to the [Gatsby Starter Library](/contributing/submit-to-starter-library/). Add tags to your starter by first checking for existing ones (like `contentful`, `csv`, etc.), and adding more if needed! +To make sure your starter is easily discoverable, you are welcome (but not required) to add it to the [Gatsby Starter Library](/contributing/submit-to-starter-library/). Add tags to your starter by first checking for existing ones (like `contentful`, `csv`, etc.), and adding more if needed! ## Further reading: