You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/contribute/locally.md
+61-30Lines changed: 61 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,8 +5,8 @@ Follow these steps to contribute to Elastic docs.
5
5
*[Prerequisites](#prerequisites)
6
6
*[Step 1: Install `docs-builder`](#step-one)
7
7
*[Step 2: Clone a content repository](#step-two)
8
-
*[Step 3: Serve the Documentation](#step-three)
9
-
*[Step 4: Write docs!](#step-four)
8
+
*[Step 3: Serve the documentation](#step-three)
9
+
*[Step 4: Write the docs](#step-four)
10
10
*[Step 5: Push your changes](#step-five)
11
11
12
12
## Prerequisites
@@ -35,10 +35,13 @@ This guide uses the first option. If you'd like to clone the repository and buil
35
35
Run this command to download and install the latest version of `docs-builder`:
36
36
37
37
```sh
38
-
sudo curl -L https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.sh| sh
38
+
curl -sL https://ela.st/docs-builder-install | sh
39
39
```
40
+
40
41
This downloads the latest binary, makes it executable, and installs it to your user PATH.
41
42
43
+
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
44
+
42
45
2.**Run docs-builder from a docs folder**
43
46
44
47
Use the `serve` command from any docs folder 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`:
@@ -47,7 +50,9 @@ This guide uses the first option. If you'd like to clone the repository and buil
47
50
docs-builder serve
48
51
```
49
52
50
-
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
53
+
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
54
+
55
+
If you get a `Permission denied` error, make sure that you aren't trying to run a directory instead of a file. Also, grant the binary file execution permissions using `chmod +x docs-builder`.
51
56
52
57
:::
53
58
@@ -58,27 +63,24 @@ To download and install the binary file manually, refer to [Releases](https://gi
58
63
Run this command to download and install the latest version of `docs-builder`:
This downloads the latest binary, makes it executable, and installs it to your user PATH.
65
70
71
+
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
72
+
66
73
2.**Run docs-builder from a docs folder**
67
74
68
75
Use the `serve` command from any docs folder 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`:
69
76
70
77
```sh
71
78
docs-builder serve
72
79
```
73
-
74
-
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
75
-
80
+
76
81
:::
77
82
::::
78
83
79
-
:::{tip}
80
-
Place the `docs-builder` binary file in a system path so that you can run it from any folder. On macOS, you can do this by running `sudo mv docs-builder /usr/local/bin/docs-builder`.
81
-
:::
82
84
83
85
## Clone a content repository [#step-two]
84
86
@@ -87,42 +89,71 @@ Documentation lives in many repositories across Elastic. If you're unsure which
87
89
:::
88
90
89
91
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:
1.**Navigate to the `docs-builder` clone location:**
97
-
```sh
98
-
cd docs-content
99
-
```
99
+
Static-site generators like docs-builder can serve docs locally. This means you can edit the source and see the result in the browser in real time.
100
100
101
-
1.**Run the Binary:**
102
-
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`.
101
+
To serve the local copy of the documentation in your browser, follow these steps:
103
102
104
-
For example, if `docs-builder` and `docs-content` are in the same top-level directory, you would run:
105
-
```sh
106
-
# macOS/Linux
107
-
./docs-builder serve -p ./migration-test
103
+
::::::{stepper}
108
104
109
-
# Windows
110
-
.\docs-builder serve -p .\migration-test
111
-
```
105
+
:::::{step} Go to the docs-builder clone location
106
+
107
+
```sh
108
+
cd docs-content
109
+
```
110
+
:::::
111
+
112
+
:::::{step} Run docs-builder
113
+
114
+
Run the `docs-builder` 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`.
112
115
116
+
For example:
117
+
118
+
::::{tab-set}
119
+
120
+
:::{tab-item} macOS & Linux
121
+
122
+
```sh
123
+
docs-builder serve -p ./migration-test
124
+
```
125
+
:::
126
+
127
+
:::{tab-item} Windows
128
+
129
+
```powershell
130
+
docs-builder serve -p .\migration-test
131
+
```
132
+
:::
133
+
::::
134
+
:::::
135
+
136
+
:::::{step} Open the documentation in the browser
113
137
Now you should be able to view the documentation locally by navigating to http://localhost:3000.
138
+
:::::
139
+
::::::
114
140
115
-
## Step 4: Write docs [#step-four]
141
+
## Step 4: Write the docs [#step-four]
116
142
117
-
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.
143
+
We write docs in Markdown. Refer to 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 pizzazz to your docs.
118
144
119
145
## Step 5: Push your changes [#step-five]
120
146
121
-
After you've made your changes locally,
147
+
After you've made your changes locally:
122
148
123
149
*[Push your commits](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository)
124
150
*[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)
125
151
126
-
## Step 5: View on elastic.co/docs
152
+
## Step 5: View the preview
153
+
154
+
You can open a docs preview from the Deployments page of the repository. For example, [https://github.com/elastic/docs-content/deployments](https://github.com/elastic/docs-content/deployments).
155
+
156
+
1. Select the pull request or branch.
157
+
2. Select the ↗ icon next to the timestamp.
127
158
128
-
soon...
159
+
The preview URL is in the form `https://docs-v3-preview.elastic.dev/elastic/<repository>/tree/branch`.
0 commit comments