Add to Migration, Syntax, and Contribution Guides

.github/ISSUE_TEMPLATE/bug-report.yaml

@@ -0,0 +1,38 @@
+name: "Bug Report"
+description: "File a bug report."
+labels: ["bug"]
+projects: ["elastic/1625"]
+body:
+  - type: "textarea"
+    id: description
+    attributes:
+      label: "Describe the bug"
+      description: "A clear and concise description of what the bug is. If applicable, add screenshots to help explain your problem."
+    validations:
+      required: true
+  - type: "textarea"
+    id: expected
+    attributes:
+      label: "Expected behavior"
+      description: "A clear and concise description of what you expected to happen."
+    validations:
+      required: true
+  - type: "textarea"
+    id: repro
+    attributes:
+      label: "Steps to reproduce"
+      description: "If relevant, provide steps to reproduce the issue."
+    validations:
+      required: false
+  - type: "checkboxes"
+    id: tooling
+    attributes:
+      label: "Tooling"
+      description: "Select the tool this bug relates to."
+      options:
+      - label: "docs-builder"
+        required: false
+      - label: "migration tooling"
+        required: false
+      - label: "I'm not sure"
+        required: false

.github/ISSUE_TEMPLATE/enhancement.yaml

@@ -0,0 +1,90 @@
+name: Feature Request
+description: Suggest an idea for improving docs-builder.
+title: "[Feature Request]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to suggest an improvement to docs-builder! Please fill out this form as completely as possible.
+
+  - type: checkboxes
+    attributes:
+      label: Prerequisites
+      description: Please verify you have completed the following
+      options:
+        - label: I have searched existing issues to ensure this feature hasn't already been requested
+          required: true
+        - label: I have tested using the latest version of docs-builder
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: |
+        Describe the context and limitation you're encountering. Remember that it might not be obvious to others why this is important!
+      placeholder: |
+        Example: When building documentation for my project, I often need to update the revision date at the top of each file. Currently, I have to manually edit each file, which is time-consuming and error-prone.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: |
+        Describe your proposed solution. Include as much detail as you can, but remember that there might be other solutions we haven't thought of!
+      placeholder: |
+        Example: Add a CLI flag --auto-update-revision-date that automatically updates a specified metadata field in all documentation files when building.
+    validations:
+      required: true
+
+  - type: textarea
+    id: examples
+    attributes:
+      label: Examples and Research
+      description: |
+        Please provide any relevant examples, research, or references that support this feature request:
+        - Similar features in other documentation tools
+        - Code samples showing how you'd use this feature
+        - Links to relevant standards or conventions
+        - Screenshots or diagrams of your proposed solution
+      placeholder: |
+        - MkDocs has a similar feature using their `git-revision-date-localized` plugin
+        - Jekyll's `last_modified_at` plugin demonstrates this functionality
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternative Solutions
+      description: |
+        What alternative solutions have you considered or tried? Why aren't they sufficient?
+      placeholder: |
+        I've tried using git hooks to update the dates, but this doesn't work well in CI/CD pipelines.
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the feature request here.
+      placeholder: |
+        - This would be particularly useful for compliance documentation where revision dates are mandatory
+        - Could potentially integrate with git history for more accurate dating
+    validations:
+      required: false
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How important is this feature to you?
+      options:
+        - Nice to have
+        - Important
+        - Critical
+    validations:
+      required: true

docs/source/configure/index.md

@@ -1,4 +1,8 @@
 ---
 title: Configure Elastic Docs
 navigation_title: Configuration reference
----
+---
+
+* [Page configuration](./page.md)
+* [Content-set configuration](./content-set/index.md)
+* [Site configuration](./site/index.md)

docs/source/contribute/index.md

@@ -1,10 +1,28 @@
 ---
 title: Elastic Docs contribution guide
-navigation_title: Contribution guide
+navigation_title: Contribute
 ---
 
-Want to contribute to the Elastic documentation? You're in the right spot! Select an option below to get started:
+Welcome, **contributor**!
 
-* I just want to suggest a change --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml)
-* I want to make a small change to a single page --> [Update the docs in your _web browser_](change-browser.md).
-* I want to make a larger change or a change to multiple pages --> [Update the docs in your _code editor_](change-local.md).
+Whether you're a technical writer or you've only edited Elastic docs once or twice, you're a valued contributor. Every word matters!
+
+## Contribute to the docs [#contribute]
+
+* Simple bugs and enhancements --> [Contribute on the web](on-the-web.md)
+* Complex or multi-page updates --> [Contribute locally](locally.md)
+
+## Report a bug
+
+* It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md)
+* It's a **build tool (docs-builder)** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml)
+* It's a **migration tooling** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml)
+
+## Request an enhancement
+
+* Make the **documentation** better --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml)
+* Make our **build tool (docs-builder)** better --> [Open a docs-builder issue](https://github.com/elastic/docs-builder/issues/new?template=enhancement.yaml)
+
+## Work on docs-builder
+
+That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system.

docs/source/contribute/locally.md

@@ -0,0 +1,121 @@
+---
+title: Contribute locally
+---
+
+Follow these steps to contribute to Elastic docs.
+* [Step 1: Install `docs-builder`](#step-one)
+* [Step 2: Clone the `docs-content` repository](#step-two)
+* [Step 3: Serve the Documentation](#step-three)
+* [Step 4: Open a PR](#step-three)
+
+## Step 1: Install `docs-builder` [#step-one]
+
+::::{tab-set}
+
+:::{tab-item} macOS
+
+### macOS
+
+1. **Download the Binary:**
+   Download the latest macOS binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
+   ```sh
+   curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
+   ```
+
+2. **Extract the Binary:**
+   Unzip the downloaded file:
+   ```sh
+   unzip docs-builder-mac-arm64.zip
+   ```
+
+3. **Run the Binary:**
+   Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the docset.yml file that you want to build can be specified with `-p`:
+   ```sh
+   ./docs-builder serve -p ./path/to/docs
+   ```
+
+:::
+
+:::{tab-item} Windows
+
+### Windows
+
+1. **Download the Binary:**
+   Download the latest Windows binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
+   ```sh
+   Invoke-WebRequest -Uri https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip -OutFile docs-builder-win-x64.zip
+   ```
+
+2. **Extract the Binary:**
+   Unzip the downloaded file. You can use tools like WinZip, 7-Zip, or the built-in Windows extraction tool.
+   ```sh
+   Expand-Archive -Path docs-builder-win-x64.zip -DestinationPath .
+   ```
+
+3. **Run the Binary:**
+   Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the docset.yml file that you want to build can be specified with `-p`:
+   ```sh
+   .\docs-builder serve -p ./path/to/docs
+   ```
+
+:::
+
+:::{tab-item} Linux
+
+### Linux
+
+1. **Download the Binary:**
+   Download the latest Linux binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
+   ```sh
+   wget https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-linux-x64.zip
+   ```
+
+2. **Extract the Binary:**
+   Unzip the downloaded file:
+   ```sh
+   unzip docs-builder-linux-x64.zip
+   ```
+
+3. **Run the Binary:**
+   Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the docset.yml file that you want to build can be specified with `-p`:
+   ```sh
+   ./docs-builder serve -p ./path/to/docs
+   ```
+
+:::
+
+::::
+
+## Clone the `docs-content` Repository  [#step-two]
+
+Clone the `docs-content` repository to a directory of your choice:
+```sh
+git clone https://github.com/elastic/docs-content.git
+```
+
+## Serve the Documentation [#step-three]
+
+1. **Navigate to the cloned repository:**
+   ```sh
+   cd docs-content
+   ```
+
+2. **Run the Binary:**
+   Use the `serve` command to start serving the documentation at http://localhost:5000. The path to the `docset.yml` file that you want to build can be specified with `-p`:
+   ```sh
+   # macOS/Linux
+   ./docs-builder serve -p ./migration-test
+
+   # Windows
+   .\docs-builder serve -p .\migration-test
+   ```
+
+Now you should be able to view the documentation locally by navigating to http://localhost:5000.
+
+## Step 4: Open a PR [#step-four]
+
+Open a PR. Good luck.
+
+## Step 5: View on elastic.co/docs
+
+soon...

docs/source/contribute/on-the-web.md

@@ -0,0 +1,12 @@
+---
+title: Contribute on the web
+---
+
+:::{warning}
+This feature is not supported yet. See [#171](https://github.com/elastic/docs-builder/issues/171) for more information.
+:::
+
+1. On the right side of the page you want to edit, select **Edit this page**.
+1. Do something on GitHub.
+1. Take the dog for a walk.
+1. Success!

docs/source/development/link-validation.md

@@ -0,0 +1,52 @@
+---
+title: Link validation
+---
+
+* See the [RFC](https://docs.google.com/document/d/1fZNeJCVLKu19s4WIKkkqrHyE9YlWQHNed94Y_V7ofRI/edit?tab=t.0#heading=h.z8tixe192fr4).
+* Infrastructure lives in [docs-infra](https://github.com/elastic/docs-infra).
+
+The mermaid chart below is currently unsupported.
+
+```
+flowchart TD
+    subgraph **Repository Build Process**
+        direction LR
+        subgraph Repositories
+            A[Repository A] --> Z1
+            B[Repository B] --> Z2
+            C[Repository C] --> Z3
+            Z1[Link validation process]
+            Z2[Link validation process]
+            Z3[Link validation process]
+        end
+        Z1 & Z2 & Z3 -->|If validation succeeds| E[Generate links.json]
+        E -->|Extract external links and add to _external_links_ array| H
+        H[Upload updated links.json to S3]
+    end
+
+    subgraph AWS **Link Index**
+        H --> I[Amazon S3 Bucket]
+        I --> J[CloudFront Distribution]
+    end
+
+    subgraph Assembler
+        J --> X["Validate links and build docs (TBD)"]
+    end
+
+    subgraph **Link validation process**
+        subgraph Changes to md files
+            Q[Add External Links] --> K
+            R[Remove Markdown Files] --> K
+        end
+        K[Docs build kicks off]
+        K --> L[Download links.json files from CloudFront]
+        L --> M{Link Validation}
+        M -->|All Links Valid| N[Build Succeeds]
+        M -->|Broken Links Found| O[Build Fails]
+    end
+
+    J --> L
+
+    style N fill:#a3d9a5,color:#333
+    style O fill:#f8a5a5,color:#333
+```

docs/source/development/toc.yml

@@ -1,2 +1,3 @@
 toc:
   - file: index.md
+  - file: link-validation.md