Add Community area and docs (#45)

CONTRIBUTING.md

@@ -1,6 +1,42 @@
 # Contributing
 
-See <https://github.com/cucumber/.github/blob/main/CONTRIBUTING.md> for general advice on contributing to Cucumber. Please also read the [Code of Conduct](https://github.com/cucumber/.github/blob/main/CODE_OF_CONDUCT.md).
+(See <https://github.com/cucumber/.github/blob/main/CONTRIBUTING.md> for general advice on contributing to Cucumber. Please also read the [Code of Conduct](https://github.com/cucumber/.github/blob/main/CODE_OF_CONDUCT.md).)
+
+The Cucumber documentation is open source and anyone is welcome to contribute. In fact, we'd really appreciate your help!
+
+You can make changes to the documentation by forking this repo and making a pull request. The title should explain which docs you are modifying/creating and why. Each pull request should only modify/add a single topic. Please don't lump many unrelated document changes into the same pull request. If you want to modify or add multiple topics, please open one pull request per topic.
+
+Documentation content is written in Markdown.
+
+## Writing style
+
+In general, the documentation should be brief and to the point.
+
+> Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away - Antoine de Saint Exupéry
+
+Some guidelines:
+
+* Every page should start with an informational/motivational paragraph
+* Paragraphs should be short enough to be readable, but long enough to develop an idea
+* Every page should start with a `h1` heading. Sections use `h2`; subsections use `h3`
+* Break long lines. Insert a new line at around column 80. This is important because review comments can only be added to a line.
+* Write in present tense
+* Use neutral language, but try to make it a little entertaining (this is hard!)
+* Write in a platform-neutral way as much as possible. Cucumber is implemented in several languages, and the docs should not assume a particular platform
+* All documents should use [British English](https://en.wikipedia.org/wiki/British_English). Contributions in [American English](https://en.wikipedia.org/wiki/American_English) are fine - editors will do the translation.
+* Use links to external sites sparingly
+* Do not use copyrighted material (images, text or other)
+* Illustrations are great, but please use lo-fi drawings; Cucumber's design team will recreate illustrations according to Cucumber's [brand guidelines](https://github.com/cucumber-ltd/brand)
+* Try to keep your contribution *consistent* with the current documentation. For instance:
+    * Use consistent wording and formatting
+    * Use lower case when referring to concepts in a sentences: e.g. "step definition" instead of "Step Definition"
+
+### Tutorial style
+
+* Assume the reader has little or no knowledge of the topic
+* Use a conversational style
+* Make sure each step in the tutorial is clearly described
+* If needed, describe what the result of each step should be
 
 ## Polyglot content
 
@@ -52,4 +88,29 @@ This flavour of the tabs has all the properties mentioned in the previous sectio
 
 Sometimes, a bit of specific terminology varies between languages, but we still want to keep the content on one page. For these cases we can use the `<Term>` component which supports a few shorthands that are resolved to the correct language-specific terminology. You can see the available terms in [`terms.json`](./src/components/Polyglot/terms.json)
 
+## Media
+
+If you want to embed a YouTube video in a doc or blog post, you can use this (pre-imported) MDX component, passing in the video's identifier as a prop:
+
+```mdx
+Here's a video of what happened:
+
+<YouTubeVideo video="JuWEQsE7Hlo" />
+```
+
+## Small docs edits
+
+If you just want to make a small-ish edit to a doc, you can avoid the overhead of spinning up the site locally by following the "Edit this page" link at the bottom of the doc, which will take you to GitHub where you can propose an edit. Once you raise a pull request, Netlify will comment with a link to a deployed preview so you can see what your change will look like.
+
+Each pull request should only modify/add a single topic. Please don't lump many unrelated document changes into the same pull request. If you want to modify or add multiple topics, please open one pull request per topic.
+
+## Running locally
+
+The site is built with [Docusaurus](https://docusaurus.io/). To work on it locally, you'll need [Node.js](https://nodejs.org/) and npm installed.
+
+```shell
+npm install
+npm start
+```
 
+This starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

docs/contributing.md

@@ -0,0 +1,32 @@
+---
+description: Help us make Cucumber better
+---
+
+# Contributing
+
+You want to contribute to Cucumber, great!
+
+## You have a question
+
+You can [get in touch](/community) via Discord or GitHub Discussions, or try Stack Overflow. 
+
+## You found a bug
+
+There are several different flavours of Cucumber for different programming languages. Try to file your issue in the repo for the Cucumber flavour you're using:
+
+* [Cucumber JVM](https://github.com/cucumber/cucumber-jvm/issues/new)
+* [Cucumber JS](https://github.com/cucumber/cucumber-js/issues/new)
+* [Cucumber Ruby](https://github.com/cucumber/cucumber-ruby/issues/new)
+* [Godog](https://github.com/cucumber/godog/issues/new)
+
+If you're not sure, open an issue in the [common](https://github.com/cucumber/common/issues/new/choose) repo, and we'll take it from there.
+
+## You want to update the documentation
+
+Improvements to documentation are really valuable! See the [contribution guidelines](https://github.com/cucumber/website/blob/main/CONTRIBUTING.md) for the repo that drives this site for details.
+
+## You want to contribute but don't know how
+
+If you enjoy using Cucumber, consider [sponsoring us](/sponsors).
+
+

docusaurus.config.ts

@@ -84,6 +84,11 @@ export default {
             label: 'Documentation',
             position: 'left',
           },
+          {
+            to: '/community',
+            label: 'Community',
+            position: 'left',
+          },
           {
             to: '/blog',
             label: 'Blog',

netlify.toml

@@ -32,7 +32,7 @@
   to = "/sponsors"
   status = 301
 
-# Vanity URLs for external sites/services
+# Vanity URLs for external stuff
 [[redirects]]
   from = "/conduct"
   to = "https://github.com/cucumber/.github/tree/main?tab=coc-ov-file"
@@ -66,4 +66,18 @@
 [[redirects]]
   from = "/blog/bdd/keep-your-scenarios-brief-(1)"
   to = "/blog/bdd/keep-your-scenarios-brief"
+  status = 301
+
+# Relocated docs
+[[redirects]]
+  from = "/docs/community/get-in-touch"
+  to = "/docs/community"
+  status = 301
+[[redirects]]
+  from = "/docs/community/contributing"
+  to = "/docs/contributing"
+  status = 301
+[[redirects]]
+  from = "/docs/community/contributing-to-documentation"
+  to = "https://github.com/cucumber/website/blob/main/CONTRIBUTING.md"
   status = 301

src/components/Newsletter/Subscribe.module.scss

@@ -0,0 +1,22 @@
+.form {
+  vertical-align: baseline;
+}
+
+.field {
+  background-color: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: calc(0.875rem * var(--ifm-button-size-multiplier));
+  line-height: 1.5;
+  width: 15em;
+  padding: calc(var(--ifm-button-padding-vertical) * var(--ifm-button-size-multiplier));
+  border: var(--ifm-button-border-width) solid var(--ifm-color-gray-700);
+  border-radius: var(--ifm-button-border-radius);
+  margin-right: 0.5em;
+  vertical-align: baseline;
+}
+
+.submit {
+  font-family: inherit;
+  vertical-align: baseline;
+}

src/components/Newsletter/Subscribe.tsx

@@ -0,0 +1,30 @@
+import { FC } from 'react'
+import styles from './Subscribe.module.scss'
+import clsx from 'clsx'
+
+export const Subscribe: FC = () => {
+  return (
+    <>
+      <p className="margin-bottom--sm">Subscribe to the Cucumber newsletter:</p>
+      <form
+        action="https://buttondown.com/api/emails/embed-subscribe/cucumber"
+        method="post"
+        target="_blank"
+        className={styles.form}
+      >
+        <input
+          type="email"
+          name="email"
+          placeholder="[email protected]"
+          required
+          className={styles.field}
+        />
+        <input type="hidden" name="embed" value="1" />
+        <input type="hidden" name="tag" value="cucumber.io" />
+        <button type="submit" className={clsx('button', 'button--primary', styles.submit)}>
+          Subscribe
+        </button>
+      </form>
+    </>
+  )
+}

src/components/Newsletter/index.ts

@@ -0,0 +1 @@
+export * from './Subscribe'

src/css/custom.scss

@@ -34,7 +34,7 @@
 }
 
 .readable-blurb {
-  max-width: 60rem !important;
+  max-width: 40rem !important;
   margin-left: auto;
   margin-right: auto;
 }

src/pages/community.module.scss

@@ -0,0 +1,4 @@
+.platformLogo {
+  max-width: 80%;
+  max-height: 75px;
+}

src/pages/community.tsx

@@ -0,0 +1,88 @@
+import Layout from '@theme/Layout'
+import React from 'react'
+import clsx from 'clsx'
+import styles from './community.module.scss'
+import Link from '@docusaurus/Link'
+import { Subscribe } from '@site/src/components/Newsletter'
+
+export default function Community() {
+  return (
+    <Layout>
+      <main>
+        <div className="container readable-blurb text--center padding-vert--lg">
+          <h1>The Cucumber Community</h1>
+          <p>
+            Cucumber has a thriving community made up of kinds of people, from the project's
+            long-standing maintainers to first-time users and everyone in between.
+          </p>
+          <Subscribe />
+        </div>
+        <div className="container text--center padding-vert--lg">
+          <h2>Where to find us</h2>
+          <p className="readable-blurb margin-bottom--lg">
+            Wherever you interact with the Cucumber community,
+            <br />
+            always remember to respect and uphold our <Link to="/conduct">Code of Conduct</Link>.
+          </p>
+          <div className="row text--center">
+            <div className="col col--4">
+              <img
+                className={clsx(styles.platformLogo, 'margin-bottom--md')}
+                alt=""
+                src="/img/community/discord.svg"
+              />
+              <p className="padding-horiz--sm">
+                We're now on <strong>Discord</strong> for day-to-day chat about all things Cucumber.
+                Drop by and say hello.
+              </p>
+              <Link className="button button--secondary" to="https://discord.gg/8YXBH8j74w">
+                Join our Server
+              </Link>
+            </div>
+            <div className="col col--4">
+              <img
+                className={clsx(styles.platformLogo, 'margin-bottom--md')}
+                alt=""
+                src="/img/community/github.svg"
+              />
+              <p className="padding-horiz--sm">
+                If you have questions about using Cucumber, or ideas for improving it, try our{' '}
+                <strong>GitHub Discussions</strong>.
+              </p>
+              <Link
+                className="button button--secondary"
+                to="https://github.com/orgs/cucumber/discussions"
+              >
+                Browse Discussions
+              </Link>
+            </div>
+            <div className="col col--4">
+              <img
+                className={clsx(styles.platformLogo, 'margin-bottom--md')}
+                alt=""
+                src="/img/community/stack-overflow.svg"
+              />
+              <p className="padding-horiz--sm">
+                Stuck? Many people use <strong>Stack Overflow</strong> to ask or answer questions
+                about Cucumber.
+              </p>
+              <Link
+                className="button button--secondary"
+                to="https://stackoverflow.com/questions/tagged/cucumber"
+              >
+                Find Answers
+              </Link>
+            </div>
+          </div>
+        </div>
+        <div className="container text--center padding-vert--lg">
+          <h2>Want to contribute?</h2>
+          <p className="readable-blurb">
+            There are many kinds of contributions, besides just code.{' '}
+            <Link to="/docs/contributing">You can get involved</Link>.
+          </p>
+        </div>
+      </main>
+    </Layout>
+  )
+}

src/pages/sponsors.tsx

@@ -57,7 +57,7 @@ const Tiers: FC = () => {
                 <p className="margin-top--md">{tier.description}</p>
               </div>
               <div className="card__footer">
-                <Link className="button button--block button--primary" href={tier.url}>
+                <Link className="button button--block button--secondary" href={tier.url}>
                   Sponsor
                 </Link>
               </div>
@@ -82,26 +82,29 @@ export default function Sponsors() {
             flavoured implementations of Cucumber. That's a lot of work!
           </p>
           <p>
-            Your sponsorship ensures the team can get paid for their time, and ensures Cucumber will
+            Financial contributions ensure team can get paid for their time, and that Cucumber will
             remain a reliable and fun way to test your software for years to come.
           </p>
+          <p>
+            <Link
+              className="button button--lg button--primary"
+              href="https://opencollective.com/cucumber/donate"
+            >
+              Donate Now
+            </Link>
+          </p>
         </div>
         <div className="container padding-vert--lg">
           <div className="margin-bottom--lg">
-            <p className="text--center margin-bottom--sm">
-              If you can, we'd love for you to commit a regular amount to support Cucumber
+            <p className="text--center">
+              If you can, we'd love for you to commit a regular amount to support Cucumber.
             </p>
             <Tiers />
           </div>
           <div className="text--center">
-            <p className="margin-bottom--sm">Or, you can always make a one-time donation</p>
-            <p>
-              <Link
-                className="button button--lg button--secondary"
-                href="https://opencollective.com/cucumber/donate"
-              >
-                Donate
-              </Link>
+            <p className="margin-bottom--sm">
+              Or, you can always make a{' '}
+              <Link href="https://opencollective.com/cucumber/donate">one-time donation</Link>.
             </p>
           </div>
         </div>