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
Will spin up all our services and clone and build all the documentation sets.
19
+
20
+
```markdown
21
+
dotnet run --project aspire -- --assume-cloned --skip-private-repositories
22
+
```
23
+
24
+
`--assume-cloned` will assume a documentation set set is already cloned if available locally.
25
+
26
+
`--skip-private-repositories` will skip cloning private repositories. It will also inject our `docs-builder docs into the
27
+
navigation. This allows us to validate new features' effect on the assembly process.
28
+
29
+
Our [Integration Tests](./tests-integration/Elastic.Assembler.IntegrationTests) use this exact command to validate the
30
+
assembler builds.
31
+
32
+
## Continuously build all assets during development.
33
+
34
+
```shell
35
+
./build.sh watch
36
+
```
37
+
38
+
This will monitor code, cshtml template files & static files and reload the application
39
+
if any changes.
40
+
41
+
Web assets are reloaded through `parcel watch` and don't require a recompilation.
42
+
43
+
Markdown files are refreshed automatically through livereload
44
+
45
+
Code or layout changes will relaunch the server automatically
46
+
47
+
# Release Process
48
+
49
+
This section outlines the process for releasing a new version of this project.
50
+
51
+
## Versioning
52
+
53
+
This project uses [Semantic Versioning](https://semver.org/) and its version is
54
+
automatically determined by [release-drafter](https://github.com/release-drafter/release-drafter)
55
+
based on the labels of the pull requests merged into the `main` branch.
56
+
57
+
See the [release-drafter configuration](./.github/release-drafter.yml) for more details.
58
+
59
+
## Creating a New Release
60
+
61
+
To create a new release trigger the [release](https://github.com/elastic/docs-builder/actions/workflows/release.yml) workflow on the `main` branch.
62
+
63
+
Every time a pull request is merged into the `main` branch, release-drafter will
64
+
create a draft release or update the existing draft release in the [Releases](https://github.com/elastic/docs-builder/releases) page.
65
+
66
+
To create a new release you need to publish the existing draft release created by release-drafter.
67
+
68
+
> [!IMPORTANT]
69
+
> Make sure the [release-drafter workflow](https://github.com/elastic/docs-builder/actions/workflows/release-drafter.yml) is finished before publishing the release.
70
+
71
+
> [!NOTE]
72
+
> When a release is published, the [create-major-tag workflow](./.github/workflows/create-major-tag.yml)
73
+
> will force push a new major tag in the format `vX` where `X` is the major version of the release.
74
+
> For example, if the release is `1.2.3` was published, the workflow will force push a new tag `v1` on the same commit.
Converts a source markdown folder or file to an output folder
20
-
21
-
Options:
22
-
-p|--path <string?> Defaults to the`{pwd}/docs` folder (Default: null)
23
-
-o|--output <string?> Defaults to `.artifacts/html` (Default: null)
24
-
--path-prefix <string?> Specifies the path prefix for urls (Default: null)
25
-
--force <bool?> Force a full rebuild of the destination folder (Default: null)
26
-
27
-
Commands:
28
-
generate Converts a source markdown folder or file to an output folder
29
-
serve Continuously serve a documentation folder at http://localhost:3000.
30
-
diff validate Validates redirect rules have been applied to the current branch.
31
-
File systems changes will be reflected without having to restart the server.
32
-
```
14
+
The documentation files:
15
+
* are written in common Markdown with [Additional syntax extensions](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/) to produce a richer writing and reading experience.
16
+
* By conventions the documentation lives in `docs` folder but the tooling will look for any folder holding the `docset.yml` configuration file given the current working directory.
33
17
34
-
In the near term native code will be published by CI for the following platforms
18
+
## Distributed documentation
35
19
36
-
| OS | Architectures |
37
-
|----------|---------------|
38
-
| Windows | x64, Arm64 |
39
-
| Linux | x64, Arm64 |
40
-
| macOS | x64, Arm64 |
20
+
The main driver for folks writing documentation is `docs-builder`.
21
+
This tool builds each repository in isolation and in addition produces a full mapping of all the linkable resources it contains in a `links.json` file.
41
22
42
-
And we'll invest time in making sure these are easily obtainable (`brew`, `winget`, `apt`)
23
+
Each time a repository successfully builds on its respective main integration branch, our automation will publish its links.json file.
24
+
For example, [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) representing all linkable resources in the Elasticsearch repository.
43
25
44
-
For now you can run the tool locally through `docker run`
26
+
The `docs-assembler` tool then assembles all the repositories in the [link-registry](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json) using their last known good commit.
45
27
46
-
```bash
47
-
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
48
-
ghcr.io/elastic/docs-builder:edge
49
-
```
28
+
This allows us to:
50
29
51
-
This ensures `.git`/`docs` and `.artifacts` (the default output directory) are mounted.
30
+
* Validate outbound and inbound links ahead of time, even during local `docs-builder` builds.
31
+
* Snapshot builds: only building commits that produced a `links.json`
32
+
* Documentation errors in one repository won't affect all the others.
33
+
* Resilient to repositories having build failures on their integration branches, we fall back to the last known good commit.
52
34
53
-
The tool will default to incremental compilation.
54
-
Only the changed files on subsequent runs will be compiled unless you pass `--force`
55
-
to force a new compilation.
35
+
## Installation
56
36
37
+
### Linux / OSX
57
38
```bash
58
-
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
Installing through the script will download the latest version of the tool and make it available in your `PATH`.
48
+
49
+
If you want to manually install the tool you can download the latest release from the [Releases Page](https://github.com/elastic/docs-builder/releases)
63
50
64
-
Through the `serve` command you can continuously and partially compile your documentation.
51
+
### Building locally
52
+
53
+
Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
65
54
66
55
```bash
67
-
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
Note the docker image is `linux-x86` and will be somewhat slower to invoke on OSX due to virtualization.
65
+
Our [Documentation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/locally)is the best place to learn how to start using the tool locally.
75
66
67
+
The TLDR, however, is
68
+
69
+
* Running `docs-builder` from the root of any checkout with a `docs` folder will build the documentation.
70
+
* Running `docs-builder` consecutively will only rebuild the documentation that has changed.
71
+
* Running `docs-builder` with the `--force` flag will force a full rebuild of the documentation.
72
+
* You can target different folders by passing a path to `docs-builder --path <path>`
73
+
* Running `docs-builder serve` will provide a local server with live reloading.
74
+
* You can leave this command running while you add/remove/rename files in your `docs` folder.
75
+
76
+
77
+
### Other commands to know:
78
+
79
+
*`docs-builder mv`[Move files and folders](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/move)
80
+
*`docs-builder diff validate`[Manage redirects across doc sets](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/redirects#validation)
81
+
*`docs-builder inbound-links validate-link-reference` can be used after a build to validate the local `links.json` against all published documentation.
76
82
77
-
## Github Action
78
83
79
-
The `docs-builder` tool is available as github action.
84
+
## Github Action
80
85
81
-
Since it runs from a precompiled distroless image `~25mb` it's able to execute snappy. (no need to wait for building the tool itself)
86
+
The `docs-builder` tool is available as a GitHub action.
82
87
88
+
It runs as native code on a distroless image `~25mb` so there is little overhead invoking the tooling.
83
89
84
90
```yaml
85
91
jobs:
@@ -91,12 +97,9 @@ jobs:
91
97
uses: elastic/docs-builder@main
92
98
```
93
99
94
-
95
-
96
100
### GitHub Pages
97
101
98
-
To set up the tool to publish to GitHub pages use the following configuration.
99
-
**NOTE**: In the near feature we'll make this a dedicated single step GitHub action
102
+
To set up the tool to publish to GitHub Pages, use the following configuration.
100
103
101
104
```yaml
102
105
environment:
@@ -110,6 +113,8 @@ steps:
110
113
id: deployment
111
114
```
112
115
116
+
This single action will build and validate the documentation before publishing.
117
+
113
118
Make sure your repository settings are set up to deploy from GitHub actions see:
If documentation is moved, renamed or deleted, `docs-builder` can verify if changes in the working branch in relation to the default branch are reflected in the repository's `redirects.yml`. Verification in the local machine is currently supported.
125
-
126
-
`docs-builder diff validate <path>`
127
-
128
-
`<path>`is an optional parameter to customize the documentation folder path. It defaults to `docs`.
129
-
130
-
---
131
-
132
-
## Run without docker
133
-
134
-
You can use the .NET CLI to publish a self-contained `docs-builder` native code
135
-
binary. (On my M2 Pro mac the binary is currently 16mb)
136
-
137
-
Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
## Continuously build all assets during development.
161
-
162
-
```shell
163
-
./build.sh watch
164
-
```
165
-
166
-
This will monitor code, cshtml template files & static files and reload the application
167
-
if any changes.
168
-
169
-
Web assets are reloaded through `parcel watch` and don't require a recompilation.
170
-
171
-
Markdown files are refreshed automatically through livereload
172
-
173
-
Code or layout changes will relaunch the server automatically
174
-
175
-
# Release Process
176
-
177
-
This section outlines the process for releasing a new version of this project.
178
-
179
-
## Versioning
180
-
181
-
This project uses [Semantic Versioning](https://semver.org/) and its version is
182
-
automatically determined by [release-drafter](https://github.com/release-drafter/release-drafter)
183
-
based on the labels of the pull requests merged into the `main` branch.
184
-
185
-
See the [release-drafter configuration](./.github/release-drafter.yml) for more details.
186
-
187
-
## Creating a New Release
188
-
189
-
To create a new release trigger the [release](https://github.com/elastic/docs-builder/actions/workflows/release.yml) workflow on the `main` branch.
190
-
191
-
Every time a pull request is merged into the `main` branch, release-drafter will
192
-
create a draft release or update the existing draft release in the [Releases](https://github.com/elastic/docs-builder/releases) page.
193
-
194
-
To create a new release you need to publish the existing draft release created by release-drafter.
195
-
196
-
> [!IMPORTANT]
197
-
> Make sure the [release-drafter workflow](https://github.com/elastic/docs-builder/actions/workflows/release-drafter.yml) is finished before publishing the release.
198
-
199
-
> [!NOTE]
200
-
> When a release is published, the [create-major-tag workflow](./.github/workflows/create-major-tag.yml)
201
-
> will force push a new major tag in the format `vX` where `X` is the major version of the release.
202
-
> For example, if the release is `1.2.3` was published, the workflow will force push a new tag `v1` on the same commit.
129
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to develop locally and contribute to the project.
0 commit comments