From dd7231a4d757a3369221054d5a9a2598b3929df7 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Wed, 12 Feb 2025 09:38:23 -0800 Subject: [PATCH 1/4] update contributor guide Signed-off-by: bmorelli25 --- docs/contribute/index.md | 3 +-- docs/contribute/locally.md | 55 +++++++++++++++++++++++++++++--------- 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index e5a29a5a8..fdbf2e4d0 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -18,12 +18,11 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi * 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) +* Make our **build tool (docs-builder)** better --> [Start a docs-builder discussion](https://github.com/elastic/docs-builder/discussions) ## Work on docs-builder diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index 7818afbe7..08eb9c0f2 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -1,13 +1,31 @@ # Contribute locally Follow these steps to contribute to Elastic docs. + +* [Prerequisites](#prerequisites) * [Step 1: Install `docs-builder`](#step-one) -* [Step 2: Clone the `docs-content` repository](#step-two) +* [Step 2: Clone a content repository](#step-two) * [Step 3: Serve the Documentation](#step-three) -* [Step 4: Open a PR](#step-three) +* [Step 4: Write docs!](#step-four) +* [Step 5: Push your changes](#step-five) + +## Prerequisites + +To write and push updates to Elastic documentation, you need the following: + +1. **A code editor**: we recommend [Visual Studio Code](https://code.visualstudio.com/download) +1. **Git installed on your machine**: learn how [here](https://github.com/git-guides/install-git) +1. **A GitHub account**: sign up [here](https://github.com/) ## Step 1: Install `docs-builder` [#step-one] +There are two different ways to install and run `docs-builder`: + +1. Download, extract, and run the binary (recommended) +1. Clone the repository and build the binary from source + +This guide uses option one. If you'd like to clone the repository and build from source, learn how in the [project readme](https://github.com/elastic/docs-builder?tab=readme-ov-file#docs-builder). + ::::{tab-set} :::{tab-item} macOS @@ -27,7 +45,7 @@ Follow these steps to contribute to Elastic docs. ``` 3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the docset.yml file that you want to build can be specified with `-p`: + Use the `serve` command to start serving the documentation at http://localhost:3000. 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 ``` @@ -51,7 +69,7 @@ Follow these steps to contribute to Elastic docs. ``` 3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the docset.yml file that you want to build can be specified with `-p`: + Use the `serve` command to start serving the documentation at http://localhost:3000. 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 ``` @@ -75,7 +93,7 @@ Follow these steps to contribute to Elastic docs. ``` 3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the docset.yml file that you want to build can be specified with `-p`: + Use the `serve` command to start serving the documentation at http://localhost:3000. 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 ``` @@ -84,22 +102,28 @@ Follow these steps to contribute to Elastic docs. :::: -## Clone the `docs-content` Repository [#step-two] +## Clone a content repository [#step-two] + +:::{tip} +Documentation lives in many repositories across Elastic. If you're unsure which repository to clone, you can use the "Edit this page" link on any documentation page to determine where the source file lives. +::: -Clone the `docs-content` repository to a directory of your choice: +In this guide, we'll clone the [`docs-content`](https://github.com/elastic/docs-content) repository. The `docs-content` repository is the home for narrative documentation at Elastic. Clone this repo 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:** +1. **Navigate to the `docs-builder` clone location:** ```sh cd docs-content ``` -2. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: +1. **Run the Binary:** + Run the binary with the `serve` command to build and serve the content set to http://localhost:3000. Specify the path to the `docset.yml` file that you want to build with `-p`. + + For example, if `docs-builder` and `docs-content` are in the same top-level directory, you would run: ```sh # macOS/Linux ./docs-builder serve -p ./migration-test @@ -110,9 +134,16 @@ git clone https://github.com/elastic/docs-content.git Now you should be able to view the documentation locally by navigating to http://localhost:3000. -## Step 4: Open a PR [#step-four] +## Step 4: Write docs [#step-four] + +We write docs in markdown. See our [syntax](../syntax/index.md) guide for the flavor of markdown that we support and all of our custom directives that enable you to add a little extra pizazz to your docs. + +## Step 5: Push your changes [#step-five] + +After you've made your changes locally, -Open a PR. Good luck. +* [Push your commits](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) +* [Open a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) ## Step 5: View on elastic.co/docs From 687b77f98df058cb0a128482d14c6669114869aa Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Wed, 12 Feb 2025 09:40:48 -0800 Subject: [PATCH 2/4] add new uri Signed-off-by: bmorelli25 --- docs/docset.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docset.yml b/docs/docset.yml index 52eb412e5..74139c204 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -21,6 +21,7 @@ external_hosts: - github.io - github.com - elastic.dev + - visualstudio.com exclude: - '_*.md' subs: From 2d81d54ed3afa135fc4715d8de71089839c2b91c Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Wed, 12 Feb 2025 09:54:02 -0800 Subject: [PATCH 3/4] update guide --- docs/contribute/index.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index fdbf2e4d0..9f64ea340 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,9 +10,21 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi ## 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) -* Test migrated content --> [Migration guide](../migration/guide/index.md) +:::{tip} +Starting with Elastic Stack version 9.0, Elastic documentation uses `docs-builder` to build documentation. Elastic Stack versions prior to 9.0 use our [legacy documentation build system](https://github.com/elastic/docs). The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. +::: + +### Contribute to Elastic Stack version 8.x docs and earlier + +To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system using AsciiDoc as it's authoring format. + +* For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) +* For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) + +### Contribute to Elastic Stack version 9.0 docs and later + +* For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) +* For **complex or multi-page updates** --> [Contribute locally](locally.md) ## Report a bug From 23a2aa96585e6b3330c83516a795e7f6eade536a Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Wed, 12 Feb 2025 09:57:10 -0800 Subject: [PATCH 4/4] small fix Signed-off-by: bmorelli25 --- docs/contribute/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 9f64ea340..0af35e1c1 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,13 +10,11 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi ## Contribute to the docs [#contribute] -:::{tip} -Starting with Elastic Stack version 9.0, Elastic documentation uses `docs-builder` to build documentation. Elastic Stack versions prior to 9.0 use our [legacy documentation build system](https://github.com/elastic/docs). The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. -::: +The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. ### Contribute to Elastic Stack version 8.x docs and earlier -To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system using AsciiDoc as it's authoring format. +To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation)