Skip to content

Commit fd41349

Browse files
bmorelli25bmorelli25
committed
more docs updates
1 parent f0c347a commit fd41349

File tree

21 files changed

+5387
-22
lines changed

21 files changed

+5387
-22
lines changed

‎docs/source/build/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Docs build internals
3+
---
4+
5+
Placeholder for now.
6+
7+
* [Link validation](link-validation.md)

‎docs/source/build/infra.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: AWS
3+
---
4+
5+
Placeholder

‎docs/source/build/link-validation.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Link validation
3+
---
4+
5+
* See the [RFC](https://docs.google.com/document/d/1fZNeJCVLKu19s4WIKkkqrHyE9YlWQHNed94Y_V7ofRI/edit?tab=t.0#heading=h.z8tixe192fr4).
6+
* Infrastructure lives in [docs-infra](https://github.com/elastic/docs-infra).
7+
8+
```{mermaid}
9+
flowchart TD
10+
subgraph **Repository Build Process**
11+
direction LR
12+
subgraph Repositories
13+
A[Repository A] --> Z1
14+
B[Repository B] --> Z2
15+
C[Repository C] --> Z3
16+
Z1[Link validation process]
17+
Z2[Link validation process]
18+
Z3[Link validation process]
19+
end
20+
Z1 & Z2 & Z3 -->|If validation succeeds| E[Generate links.json]
21+
E -->|Extract external links and add to _external_links_ array| H
22+
H[Upload updated links.json to S3]
23+
end
24+
25+
subgraph AWS **Link Index**
26+
H --> I[Amazon S3 Bucket]
27+
I --> J[CloudFront Distribution]
28+
end
29+
30+
subgraph Assembler
31+
J --> X["Validate links and build docs (TBD)"]
32+
end
33+
34+
subgraph **Link validation process**
35+
subgraph Changes to md files
36+
Q[Add External Links] --> K
37+
R[Remove Markdown Files] --> K
38+
end
39+
K[Docs build kicks off]
40+
K --> L[Download links.json files from CloudFront]
41+
L --> M{Link Validation}
42+
M -->|All Links Valid| N[Build Succeeds]
43+
M -->|Broken Links Found| O[Build Fails]
44+
end
45+
46+
J --> L
47+
48+
style N fill:#a3d9a5,color:#333
49+
style O fill:#f8a5a5,color:#333
50+
```

‎docs/source/configure/index.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
---
22
title: Configure Elastic Docs
33
navigation_title: Configuration reference
4-
---
4+
---
5+
6+
* [Page configuration](./page.md)
7+
* [Content-set configuration](./content-set/index.md)
8+
* [Site configuration](./site/index.md)

‎docs/source/contribute/change-browser.md‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
11
---
2-
title: Update the docs locally
3-
---
4-
5-
1. Install dependencies
6-
2. Clone repositories
7-
3. Make changes
8-
4. Open a Pull Request
9-
5. Work with CI
10-
6. Get approvals and merge
11-
7. View your changes live on elastic.co
2+
title: Update the docs in your browser
3+
---

‎docs/source/contribute/change-local.md‎

Lines changed: 113 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,115 @@
11
---
2-
title: Update the docs in your web browser
2+
title: Build the docs locally
33
---
4+
5+
1. Install dependencies
6+
2. Clone repositories
7+
3. Make changes
8+
4. Open a Pull Request
9+
5. Work with CI
10+
6. Get approvals and merge
11+
7. View your changes live on elastic.co
12+
13+
Follow these instructions to get started with docs-builder on your machine.
14+
15+
::::{tab-set}
16+
17+
:::{tab-item} macOS
18+
19+
### macOS Installation
20+
21+
1. **Download the Binary:**
22+
Download the latest macOS binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
23+
```sh
24+
curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
25+
```
26+
27+
2. **Extract the Binary:**
28+
Unzip the downloaded file:
29+
```sh
30+
unzip docs-builder-mac-arm64.zip
31+
```
32+
33+
3. **Run the Binary:**
34+
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`:
35+
```sh
36+
./docs-builder serve -p ./path/to/docs
37+
```
38+
39+
:::
40+
41+
:::{tab-item} Windows
42+
43+
### Windows Installation
44+
45+
1. **Download the Binary:**
46+
Download the latest Windows binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
47+
```sh
48+
Invoke-WebRequest -Uri https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip -OutFile docs-builder-win-x64.zip
49+
```
50+
51+
2. **Extract the Binary:**
52+
Unzip the downloaded file. You can use tools like WinZip, 7-Zip, or the built-in Windows extraction tool.
53+
```sh
54+
Expand-Archive -Path docs-builder-win-x64.zip -DestinationPath .
55+
```
56+
57+
3. **Run the Binary:**
58+
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`:
59+
```sh
60+
.\docs-builder serve -p ./path/to/docs
61+
```
62+
63+
:::
64+
65+
:::{tab-item} Linux
66+
67+
### Linux Installation
68+
69+
1. **Download the Binary:**
70+
Download the latest Linux binary from [releases](https://github.com/elastic/docs-builder/releases/latest/):
71+
```sh
72+
wget https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-linux-x64.zip
73+
```
74+
75+
2. **Extract the Binary:**
76+
Unzip the downloaded file:
77+
```sh
78+
unzip docs-builder-linux-x64.zip
79+
```
80+
81+
3. **Run the Binary:**
82+
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`:
83+
```sh
84+
./docs-builder serve -p ./path/to/docs
85+
```
86+
87+
:::
88+
89+
::::
90+
91+
### Clone the `docs-content` Repository
92+
93+
Clone the `docs-content` repository to a directory of your choice:
94+
```sh
95+
git clone https://github.com/elastic/docs-content.git
96+
```
97+
98+
### Serve the Documentation
99+
100+
1. **Navigate to the cloned repository:**
101+
```sh
102+
cd docs-content
103+
```
104+
105+
2. **Run the Binary:**
106+
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`:
107+
```sh
108+
# macOS/Linux
109+
./docs-builder serve -p ./migration-test
110+
111+
# Windows
112+
.\docs-builder serve -p .\migration-test
113+
```
114+
115+
Now you should be able to view the documentation locally by navigating to http://localhost:5000.

‎docs/source/docset.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@ toc:
2424
- folder: migration
2525
children:
2626
- file: index.md
27+
- file: guide.md
2728
- file: file-structure.md
29+
- file: mapping.md
30+
- file: tabs.md
31+
- file: codeowner.md
2832
- folder: contribute
2933
children:
3034
- file: index.md

‎docs/source/migration/codeowner.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Documentation freeze CODEOWNERS
3+
---
4+
5+
This document lists the CODEOWNERS configuration used to enforce documentation freezes across Elastic repositories. During a documentation freeze, the `@docs-freeze-team` must approve any pull requests that modify documentation files (`.asciidoc`) before they can be merged. This prevents unintended documentation changes during crucial periods such as releases.
6+
7+
To regenerate this list, run the following commands from the repository root:
8+
9+
```sh
10+
cd docs/source/migration/scripts/codeowner-gen
11+
python3 codeowner.py
12+
```
13+
14+
This will process `conf.yaml` and generate an updated `output.md` file containing the CODEOWNERS configuration for all repositories with documentation. The output is automatically included in this README. Note that the `conf.yaml` include in this repo should be replaced by a current version before running this script again.
15+
16+
## Documentation source repositories
17+
18+
:::{include} scripts/codeowner-gen/output.md
19+
:::

‎docs/source/migration/file-structure.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ in the APM docs:
2626
* **New filename**: The page ID determines the filename of the migrated MD file:
2727
% `data-model-spans.mdx`. This file will be in the root directory of the directory containing the content for the `en/apm/guide` book.
2828
* **New URL**: The new URL for this page in the new docs system will be `xxxx`.
29-
*
29+
3030
Because a single AsciiDoc file can contain the content for multiple pages (or content
3131
displayed on a single page could be spread across multiple AsciiDoc files), the `.asciidoc`
3232
filename can be different than the `.md` filename. However, you should be able to locate

‎docs/source/migration/guide.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Migration Guide
3+
---
4+
5+
How to migrate content from Asciidoc to V3.
6+
7+
1. Clone https://github.com/elastic/adoc-to-md
8+
2. Run the migration tool
9+
3. Copy the output to the appropriate directory in https://github.com/elastic/docs-content
10+
4. Update the `docset.yml` file to reflect the new IA of the content set
11+
5. Build your changes with https://github.com/elastic/docs-builder
12+
6. Open a PR and merge your changes

0 commit comments

Comments
 (0)