Skip to content

Commit d1c3965

Browse files
authored
Merge branch 'main' into theletterf-patch-1
2 parents 102fb87 + 12e21d4 commit d1c3965

File tree

24 files changed

+407
-328
lines changed

24 files changed

+407
-328
lines changed

.github/workflows/release.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ jobs:
159159
gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-builder/release/*.zip
160160
gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-assembler/release/*.zip
161161
shell: bash
162-
162+
163163
publish-release:
164164
needs:
165165
- release

Directory.Packages.props

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,6 @@
4848
<PackageVersion Include="Vecc.YamlDotNet.Analyzers.StaticGenerator" Version="16.1.3" PrivateAssets="All" />
4949
<PackageVersion Include="Westwind.AspNetCore.LiveReload" Version="0.5.2" />
5050
<PackageVersion Include="YamlDotNet" Version="16.3.0" />
51-
<PackageVersion Include="Supernova.Enum.Generators" Version="1.0.17" />
5251
</ItemGroup>
5352
<!-- Test packages -->
5453
<ItemGroup>
@@ -64,4 +63,4 @@
6463
<PackageVersion Include="xunit.runner.visualstudio" Version="3.0.2" />
6564
<PackageVersion Include="xunit.v3" Version="1.1.0" />
6665
</ItemGroup>
67-
</Project>
66+
</Project>

docs/contribute/locally.md

Lines changed: 24 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -28,83 +28,55 @@ This guide uses the first option. If you'd like to clone the repository and buil
2828

2929
::::{tab-set}
3030

31-
:::{tab-item} macOS
31+
:::{tab-item} macOS & Linux
3232

33-
1. **Download the Binary:**
34-
Download the latest macOS binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
35-
```sh
36-
curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
37-
```
33+
1. **Download and run the install script**
3834

39-
2. **Extract the Binary:**
40-
Unzip the downloaded file:
41-
```sh
42-
unzip docs-builder-mac-arm64.zip
43-
```
35+
Run this command to download and install the latest version of `docs-builder`:
4436

45-
3. **Run the Binary:**
46-
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`:
4737
```sh
48-
./docs-builder serve -p ./path/to/docs
38+
sudo curl -L https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.sh | sh
4939
```
40+
41+
This downloads the latest binary, makes it executable, and installs it to your user PATH.
5042

51-
:::
43+
2. **Run docs-builder from a docs folder**
5244

53-
:::{tab-item} Windows
45+
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`:
5446

55-
1. **Download the Binary:**
56-
Download the latest Windows binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
5747
```sh
58-
Invoke-WebRequest -Uri https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip -OutFile docs-builder-win-x64.zip
48+
docs-builder serve
5949
```
6050

61-
2. **Extract the Binary:**
62-
Unzip the downloaded file. You can use tools like WinZip, 7-Zip, or the built-in Windows extraction tool.
63-
```sh
64-
Expand-Archive -Path docs-builder-win-x64.zip -DestinationPath .
65-
```
51+
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
6652

67-
3. **Run the Binary:**
68-
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`:
69-
70-
```sh
71-
.\docs-builder serve -p ./path/to/docs
72-
```
53+
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`.
7354

74-
:::{tip}
75-
Place the `docs-builder` binary file in a system path so that you can run it from any folder. On Windows, you can do this by running `Copy-Item "docs-builder.exe" -Destination "%SystemRoot%\system32"` with elevated privileges, or move it to a new folder and add the folder to the system paths.
7655
:::
7756

78-
:::
57+
:::{tab-item} Windows
7958

80-
:::{tab-item} Linux
59+
1. **Download and run the install script**
8160

82-
1. **Download the Binary:**
83-
Download the latest Linux binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
84-
```sh
85-
wget https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-linux-x64.zip
86-
```
61+
Run this command to download and install the latest version of `docs-builder`:
8762

88-
2. **Extract the Binary:**
89-
Unzip the downloaded file:
90-
```sh
91-
unzip docs-builder-linux-x64.zip
63+
```powershell
64+
iex (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.ps1')
9265
```
9366

94-
3. **Run the Binary:**
95-
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`:
67+
This downloads the latest binary, makes it executable, and installs it to your user PATH.
68+
69+
2. **Run docs-builder from a docs folder**
70+
71+
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`:
72+
9673
```sh
97-
./docs-builder serve -p ./path/to/docs
74+
docs-builder serve
9875
```
9976

100-
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`.
101-
102-
:::{tip}
103-
Place the `docs-builder` binary file in a system path so that you can run it from any folder. On macOS and Linux, you can do this by running `sudo mv docs-builder /usr/local/bin/docs-builder`.
104-
:::
77+
To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
10578

10679
:::
107-
10880
::::
10981

11082

docs/syntax/frontmatter.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ description: This is a description of the page <2>
1313
applies_to: <3>
1414
serverless: all
1515
products: <4>
16-
- apm-java-agent
17-
- edot-java
16+
- id: apm-java-agent
17+
- id: edot-java
1818
---
1919
```
2020

@@ -45,7 +45,7 @@ See [](./applies.md)
4545
The products frontmatter is a list of products that the page relates to.
4646
This is used for the "Products" filter in the Search UI.
4747

48-
The products frontmatter is a list of strings, each string is the id of a product.
48+
The products frontmatter is a list of objects, each object has an `id` field.
4949

5050
| Product ID | Product Name |
5151
|---------------------------------------------|-----------------------------------------------|

install.ps1

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# PowerShell script to install docs-builder binary
2+
3+
# Use AppData\Local for user-specific installation instead of Program Files
4+
$targetDir = Join-Path -Path $env:LOCALAPPDATA -ChildPath "docs-builder"
5+
$targetPath = Join-Path -Path $targetDir -ChildPath "docs-builder.exe"
6+
7+
# Check if docs-builder already exists
8+
if (Test-Path -Path $targetPath) {
9+
Write-Host "docs-builder is already installed."
10+
$choice = Read-Host -Prompt "Do you want to update/overwrite it? (y/n)"
11+
switch ($choice.ToLower()) {
12+
'y' { Write-Host "Updating docs-builder..." }
13+
'n' { Write-Host "Installation aborted."; exit 0 }
14+
Default { Write-Host "Invalid choice. Installation aborted."; exit 1 }
15+
}
16+
}
17+
18+
# Create target directory if it doesn't exist
19+
if (-not (Test-Path -Path $targetDir)) {
20+
New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
21+
}
22+
23+
# Download the latest Windows binary from releases
24+
$tempZipPath = "$env:TEMP\docs-builder-win-x64.zip"
25+
Write-Host "Downloading docs-builder binary..."
26+
Invoke-WebRequest -Uri "https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip" -OutFile $tempZipPath
27+
28+
# Create a temporary directory for extraction
29+
$tempExtractPath = "$env:TEMP\docs-builder-extract"
30+
if (Test-Path -Path $tempExtractPath) {
31+
Remove-Item -Path $tempExtractPath -Recurse -Force
32+
}
33+
New-Item -ItemType Directory -Path $tempExtractPath -Force | Out-Null
34+
35+
# Extract the binary
36+
Write-Host "Extracting binary..."
37+
Expand-Archive -Path $tempZipPath -DestinationPath $tempExtractPath -Force
38+
39+
# Copy the executable to the target location
40+
Write-Host "Installing docs-builder..."
41+
Copy-Item -Path "$tempExtractPath\docs-builder.exe" -Destination $targetPath -Force
42+
43+
# Add to PATH if not already in PATH (using User scope instead of Machine)
44+
$currentPath = [Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User)
45+
if ($currentPath -notlike "*$targetDir*") {
46+
Write-Host "Adding docs-builder to the user PATH..."
47+
[Environment]::SetEnvironmentVariable(
48+
"PATH",
49+
"$currentPath;$targetDir",
50+
[EnvironmentVariableTarget]::User
51+
)
52+
$env:PATH = "$env:PATH;$targetDir"
53+
}
54+
55+
# Clean up temporary files
56+
Remove-Item -Path $tempZipPath -Force
57+
Remove-Item -Path $tempExtractPath -Recurse -Force
58+
59+
Write-Host "docs-builder has been installed successfully and is available in your PATH."
60+
Write-Host "You may need to restart your terminal or PowerShell session for the PATH changes to take effect."

install.sh

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
#!/bin/sh
2+
set -e
3+
4+
# Determine OS type and architecture
5+
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
6+
ARCH=$(uname -m)
7+
8+
# Map architecture naming
9+
if [ "$ARCH" = "x86_64" ]; then
10+
ARCH="amd64"
11+
elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
12+
ARCH="arm64"
13+
fi
14+
15+
# Determine binary to download based on OS
16+
if [ "$OS" = "darwin" ]; then
17+
BINARY="docs-builder-mac-$ARCH.zip"
18+
DEFAULT_INSTALL_DIR="/usr/local/bin"
19+
elif [ "$OS" = "linux" ]; then
20+
BINARY="docs-builder-linux-$ARCH.zip"
21+
DEFAULT_INSTALL_DIR="/usr/local/bin"
22+
else
23+
echo "Unsupported operating system: $OS"
24+
exit 1
25+
fi
26+
27+
# Determine if we need sudo for the install directory
28+
INSTALL_DIR="$DEFAULT_INSTALL_DIR"
29+
if [ ! -w "$INSTALL_DIR" ]; then
30+
USE_SUDO=true
31+
echo "Note: Installing to $INSTALL_DIR requires administrator privileges."
32+
else
33+
USE_SUDO=false
34+
fi
35+
36+
# Check if docs-builder already exists, but handle non-interactive shells
37+
if [ -f "$INSTALL_DIR/docs-builder" ]; then
38+
echo "docs-builder is already installed."
39+
40+
# Check if script is running interactively (has a TTY)
41+
if [ -t 0 ]; then
42+
# Running interactively, can prompt for input
43+
printf "Do you want to update/overwrite it? (y/n): "
44+
read choice
45+
case "$choice" in
46+
y|Y ) echo "Updating docs-builder..." ;;
47+
n|N ) echo "Installation aborted."; exit 0 ;;
48+
* ) echo "Invalid choice. Installation aborted."; exit 1 ;;
49+
esac
50+
else
51+
# Non-interactive mode (e.g., piped from curl), default to yes
52+
echo "Running in non-interactive mode. Proceeding with installation..."
53+
fi
54+
fi
55+
56+
echo "Downloading docs-builder for $OS/$ARCH..."
57+
58+
# Download the appropriate binary
59+
curl -LO "https://github.com/elastic/docs-builder/releases/latest/download/$BINARY"
60+
61+
# Extract only the docs-builder file to /tmp directory
62+
# Use -o flag to always overwrite files without prompting
63+
unzip -j -o "$BINARY" docs-builder -d /tmp
64+
65+
# Ensure the binary is executable
66+
chmod +x /tmp/docs-builder
67+
68+
# Move the binary to the install directory
69+
echo "Installing docs-builder to $INSTALL_DIR..."
70+
if [ "$USE_SUDO" = true ]; then
71+
sudo mv -f /tmp/docs-builder "$INSTALL_DIR/docs-builder"
72+
else
73+
mv -f /tmp/docs-builder "$INSTALL_DIR/docs-builder"
74+
fi
75+
76+
# Clean up the downloaded zip file
77+
rm -f "$BINARY"
78+
79+
echo "docs-builder has been installed successfully and is available in your PATH."
80+
echo "You can run 'docs-builder --help' to see available commands."

src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@
44

55
using System.IO.Abstractions;
66
using DotNet.Globbing;
7+
using Elastic.Documentation.Configuration.Suggestions;
78
using Elastic.Documentation.Configuration.TableOfContents;
89
using Elastic.Documentation.Links;
910
using Elastic.Documentation.Navigation;
11+
using YamlDotNet.RepresentationModel;
1012

1113
namespace Elastic.Documentation.Configuration.Builder;
1214

@@ -33,6 +35,8 @@ public record ConfigurationFile : ITableOfContentsScope
3335

3436
public Dictionary<string, LinkRedirect>? Redirects { get; }
3537

38+
public HashSet<string> Products { get; } = new(StringComparer.Ordinal);
39+
3640
public HashSet<string> ImplicitFolders { get; } = new(StringComparer.OrdinalIgnoreCase);
3741

3842
public Glob[] Globs { get; } = [];
@@ -104,6 +108,36 @@ public ConfigurationFile(IDocumentationContext context)
104108
case "toc":
105109
// read this later
106110
break;
111+
case "products":
112+
if (entry.Entry.Value is not YamlSequenceNode sequence)
113+
{
114+
reader.EmitError("products must be a sequence", entry.Entry.Value);
115+
break;
116+
}
117+
118+
foreach (var node in sequence.Children.OfType<YamlMappingNode>())
119+
{
120+
YamlScalarNode? productId = null;
121+
foreach (var child in node.Children)
122+
{
123+
if (child.Key is YamlScalarNode { Value: "id" } && child.Value is YamlScalarNode scalarNode)
124+
{
125+
productId = scalarNode;
126+
break;
127+
}
128+
}
129+
if (productId?.Value is null)
130+
{
131+
reader.EmitError("products must contain an id", node);
132+
break;
133+
}
134+
135+
if (!Builder.Products.AllById.ContainsKey(productId.Value))
136+
reader.EmitError($"Product \"{productId.Value}\" not found in the product list. {new Suggestion(Builder.Products.All.Select(p => p.Id).ToHashSet(), productId.Value).GetSuggestionQuestion()}", node);
137+
else
138+
_ = Products.Add(productId.Value);
139+
}
140+
break;
107141
case "features":
108142
_features = reader.ReadDictionary(entry.Entry).ToDictionary(k => k.Key, v => bool.Parse(v.Value), StringComparer.OrdinalIgnoreCase);
109143
break;

0 commit comments

Comments
 (0)