Migrate some complex docs content (#14)

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# 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).
+
+## Polyglot content
+
+Some of the content in the docs is polyglot - that is, offered in multiple programming languages. We can vary the language-specific content within a single page using some custom React components and MDX. If the page you're editing requires polyglot content, first ensure it has an `.mdx` extension - you can rename from `.md` if needed.
+
+### Tabs
+
+You can use the `<Tabs>` and `<Tab>` components in any MDX page, without adding any imports. Example usage:
+
+```mdx
+Here is some polyglot content:
+
+<Tabs>
+    <Tab value="java">The Java content</Tab>
+    <Tab value="ruby">The Ruby content</Tab>
+    <Tab value="javascript">The JavaScript content</Tab>
+</Tabs>
+```
+
+Under the hood, this is leaning on [Docusaurus's Tabs functionality](https://docusaurus.io/docs/markdown-features/tabs). The language selection will:
+
+- Sync across different groups of tabs in the same page
+- Be remembered across different pages
+- Update the URL via the `lang` query parameter, so language-specific URLs are shareable
+
+### Term
+
+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)
+
+

docs/cucumber/_category_.json

@@ -0,0 +1,4 @@
+{
+  "position": 2,
+  "label": "Cucumber"
+}

docs/cucumber/index.mdx

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Cucumber
+
+<DocCardList />

docs/cucumber/step-definitions.mdx

@@ -0,0 +1,160 @@
+# Step definitions
+
+A Step Definition is a <Term>stepdef-body</Term> with an [expression](#expressions) that links it to one or more [Gherkin steps](/docs/gherkin/reference#steps).
+When Cucumber executes a [Gherkin step](/docs/gherkin/reference#steps) in a scenario, it will look for a matching *step definition* to execute.
+
+To illustrate how this works, look at the following Gherkin Scenario:
+
+```gherkin
+Scenario: Some cukes
+  Given I have 48 cukes in my belly
+```
+
+The `I have 48 cukes in my belly` part of the step (the text following the `Given` keyword) will match the following step definition:
+
+<Tabs>
+    <Tab value="java">
+
+```java
+package com.example;
+import io.cucumber.java.en.Given;
+
+public class StepDefinitions {
+    @Given("I have {int} cukes in my belly")
+    public void i_have_n_cukes_in_my_belly(int cukes) {
+        System.out.format("Cukes: %n\n", cukes);
+    }
+}
+```
+
+Or, using Java8 lambdas:
+
+```java
+package com.example;
+import io.cucumber.java8.En;
+
+public class StepDefinitions implements En {
+    public StepDefinitions() {
+        Given("I have {int} cukes in my belly", (Integer cukes) -> {
+            System.out.format("Cukes: %n\n", cukes);
+        });
+    }
+}
+```
+
+    </Tab>
+    <Tab value="kotlin">
+
+```kotlin
+package com.example
+import io.cucumber.java8.En
+
+class StepDefinitions : En {
+
+    init {
+        Given("I have {int} cukes in my belly") { cukes: Int ->
+                println("Cukes: $cukes")
+        }
+    }
+
+}
+```
+
+    </Tab>
+    <Tab value="scala">
+
+```scala
+package com.example
+import io.cucumber.scala.{ScalaDsl, EN}
+
+class StepDefinitions extends ScalaDsl with EN {
+
+    Given("I have {int} cukes in my belly") { cukes: Int =>
+        println(s"Cukes: $cukes")
+    }
+
+}
+```
+
+    </Tab>
+    <Tab value="ruby">
+
+```ruby
+Given('I have {int} cukes in my belly') do |cukes|
+  puts "Cukes: #{cukes}"
+end
+```
+
+    </Tab>
+    <Tab value="javascript">
+
+```javascript
+const { Given } = require('cucumber')
+
+Given('I have {int} cukes in my belly', function (cukes) {
+  console.log(`Cukes: ${cukes}`)
+});
+```
+
+    </Tab>
+</Tabs>
+
+## Expressions
+
+A step definition's *expression* can either be a [Regular Expression](https://en.wikipedia.org/wiki/Regular_expression)
+or a [Cucumber Expression](/docs/cucumber/cucumber-expressions). The examples in this section use Cucumber Expressions.
+If you prefer to use Regular Expressions, each <Term>expression-parameter</Term> from the match will be passed as arguments to the step
+definition's <Term>stepdef-body</Term>.
+
+<Tabs>
+    <Tab value="java">
+
+```java
+@Given("I have {int} cukes in my belly")
+public void i_have_n_cukes_in_my_belly(int cukes) {
+}
+```
+
+    </Tab>
+    <Tab value="kotlin">
+
+```kotlin
+Given("I have {int} cukes in my belly") { cukes: Int ->
+        println("Cukes: $cukes")
+}
+```
+
+    </Tab>
+    <Tab value="scala">
+
+```scala
+Given("I have {int} cukes in my belly") { cukes: Int =>
+    println(s"Cukes: $cukes")
+}
+```
+
+    </Tab>
+    <Tab value="ruby">
+
+```ruby
+Given(/I have {int} cukes in my belly/) do |cukes|
+end
+```
+
+    </Tab>
+    <Tab value="javascript">
+
+```javascript
+Given(/I have {int} cukes in my belly/, function (cukes) {
+});
+```
+
+    </Tab>
+</Tabs>
+
+If the <Term>expression-parameter</Term> expression is identical to one of the registered
+[parameter types](/docs/cucumber/cucumber-expressions#parameter-types)'s `regexp`,
+the captured string will be transformed before it is passed to the
+step definition's <Term>stepdef-body</Term>. In the example above, the `cukes`
+argument will be an integer, because the built-in `int` parameter type's
+`regexp` is `\d+` .

docs/gherkin/index.mdx

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Gherkin
+
+<DocCardList />

docs/gherkin/languages.mdx

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+---
+
+import { GherkinLanguages } from "@site/src/components/GherkinLanguages";
+
+# Localisation
+
+In order to allow Gherkin to be written in a number of languages, the keywords have been translated into multiple languages. To improve readability and flow, some languages may have more than one translation for any given keyword.
+
+You can find all translation of Gherkin [on GitHub](https://github.com/cucumber/gherkin).
+This is also the place to add or update translations.
+
+A list of the currently supported languages and their keywords can be found below.
+
+<GherkinLanguages/>

docs/gherkin/reference.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # Reference
 
 Gherkin uses a set of special [keywords](#keywords) to give structure and meaning to

docs/index.mdx

@@ -0,0 +1,5 @@
+---
+sidebar_position: 0
+---
+
+# Introduction

docusaurus.config.ts

@@ -64,7 +64,7 @@ export default {
         },
         items: [
           {
-            to: 'https://cucumber.io/docs/installation',
+            to: '/docs',
             label: 'Documentation',
             position: 'left'
           },
@@ -143,7 +143,7 @@ export default {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
-        additionalLanguages: ['gherkin']
+        additionalLanguages: ['gherkin', 'java', 'ruby', 'scala']
       },
     }),
 

package.json

@@ -14,6 +14,7 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
+    "@cucumber/gherkin": "^28.0.0",
     "@docusaurus/core": "3.1.1",
     "@docusaurus/preset-classic": "3.1.1",
     "@mdx-js/react": "3.0.1",

src/components/GherkinLanguages/GherkinLanguages.module.scss

@@ -0,0 +1,5 @@
+.equivalents {
+  code {
+    margin-right: 0.5em;
+  }
+}