Skip to content

Commit 6deb27c

Browse files
leemthompoleemthompo
authored
Merge branch 'main' into leemthompo/add-contribute-docs-to-nav
2 parents 7ab1d1c + fa9e8e5 commit 6deb27c

File tree

118 files changed

+8212
-1810
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

118 files changed

+8212
-1810
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,38 @@ jobs:
3737

3838
build-api-lambda:
3939
uses: ./.github/workflows/build-api-lambda.yml
40+
4041

42+
synthetics:
43+
runs-on: ubuntu-latest
44+
steps:
45+
- uses: actions/checkout@v5
46+
47+
- name: Bootstrap Action Workspace
48+
id: bootstrap
49+
uses: ./.github/actions/bootstrap
50+
51+
- name: Install dependencies
52+
working-directory: src/Elastic.Documentation.Site
53+
run: npm ci
54+
55+
- name: Run assembler
56+
run: |
57+
mkdir ../assembler-workspace
58+
cd ../assembler-workspace
59+
dotnet run --project ../docs-builder/src/tooling/docs-builder -- assembler config init --local
60+
dotnet run --project ../docs-builder/src/tooling/docs-builder -- assembler clone -c local --skip-private-repositories
61+
dotnet run --project ../docs-builder/src/tooling/docs-builder -- assembler build -c local --skip-private-repositories
62+
dotnet run --project ../docs-builder/src/tooling/docs-builder -- assembler serve &
63+
64+
- name: Wait for docs
65+
working-directory: src/Elastic.Documentation.Site
66+
run: npx wait-on http-get://localhost:4000/docs
67+
68+
- name: Run synthetics
69+
working-directory: src/Elastic.Documentation.Site
70+
run: npm run synthetics:test
71+
4172
npm:
4273
runs-on: ubuntu-latest
4374
defaults:

‎.github/workflows/detect-duplicate-issues.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ jobs:
1616
runs-on: ubuntu-latest
1717
steps:
1818
- name: Detect potential duplicate issues
19-
uses: actions/github-script@v7
19+
uses: actions/github-script@v8
2020
with:
2121
script: |
2222
const { owner, repo } = context.repo;

‎.github/workflows/preview-build.yml‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,7 @@ jobs:
334334
# we run our artifact directly, please use the prebuild
335335
# elastic/docs-builder@main GitHub Action for all other repositories!
336336
- name: Build documentation
337+
id: internal-docs-build
337338
if: >
338339
env.MATCH == 'true'
339340
&& github.repository == 'elastic/docs-builder'
@@ -385,7 +386,7 @@ jobs:
385386
&& (
386387
!cancelled()
387388
&& github.repository == 'elastic/docs-builder'
388-
&& steps.docs-build.outputs.skip != 'true'
389+
&& steps.internal-docs-build.outputs.skip != 'true'
389390
&& (
390391
steps.deployment.outputs.result
391392
|| (
@@ -404,6 +405,7 @@ jobs:
404405
!cancelled()
405406
&& github.repository != 'elastic/docs-builder'
406407
&& steps.docs-build.outputs.skip != 'true'
408+
&& steps.docs-build.outcome != 'skipped'
407409
&& (
408410
steps.deployment.outputs.result
409411
|| (
@@ -420,7 +422,8 @@ jobs:
420422
&& (
421423
!cancelled()
422424
&& github.repository == 'elastic/docs-builder'
423-
&& steps.docs-build.outputs.skip != 'true'
425+
&& steps.internal-docs-build.outputs.skip != 'true'
426+
&& steps.internal-docs-build.outcome != 'skipped'
424427
&& (
425428
steps.deployment.outputs.result
426429
|| (
@@ -435,15 +438,17 @@ jobs:
435438
- uses: elastic/docs-builder/.github/actions/aws-auth@main
436439
if: >
437440
!cancelled()
438-
&& steps.docs-build.outputs.skip != 'true'
441+
&& (steps.docs-build.outputs.skip != 'true' || steps.internal-docs-build.outputs.skip != 'true')
439442
&& steps.deployment.outputs.result
443+
&& (steps.docs-build.outcome == 'success' || steps.internal-docs-build.outcome == 'success')
440444
- name: Upload to S3
441445
id: s3-upload
442446
if: >
443447
env.MATCH == 'true'
444448
&& !cancelled()
445-
&& steps.docs-build.outputs.skip != 'true'
449+
&& (steps.docs-build.outputs.skip != 'true' || steps.internal-docs-build.outputs.skip != 'true')
446450
&& steps.deployment.outputs.result
451+
&& (steps.docs-build.outcome == 'success' || steps.internal-docs-build.outcome == 'success')
447452
run: |
448453
aws s3 sync .artifacts/docs/html "s3://elastic-docs-v3-website-preview${PATH_PREFIX}" --delete --no-follow-symlinks
449454
aws cloudfront create-invalidation \
@@ -518,15 +523,15 @@ jobs:
518523
return;
519524
}
520525
521-
const toLink = (file) => {
526+
const toMarkdownLink = (file) => {
522527
const path = file
523-
.replace('docs/', '')
524-
.replace('/index.md', '')
525-
.replace('.md', '');
528+
.replace(/^docs\//, '')
529+
.replace(/\/index.md$/, '')
530+
.replace(/\.md$/, '');
526531
return `[${file}](https://docs-v3-preview.elastic.dev${process.env.PATH_PREFIX}/${path})`;
527532
}
528533
529-
const links = changedMdFiles.map(toLink)
534+
const links = changedMdFiles.map(toMarkdownLink)
530535
531536
const body = [
532537
title,

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,3 +397,6 @@ FodyWeavers.xsd
397397

398398
# JetBrains Rider
399399
*.sln.iml
400+
401+
# Elastic synthetics
402+
.synthetics/

‎config/versions.yml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ versioning_systems:
33
# Updates for Stack versions are manual
44
stack: &stack
55
base: 9.0
6-
current: 9.1.4
6+
current: 9.1.5
77

88
# Using an unlikely high version
99
# So that our logic that would display "planned" doesn't trigger
@@ -30,7 +30,7 @@ versioning_systems:
3030
current: 1.15.0
3131
curator:
3232
base: 8.0
33-
current: 8.0.21
33+
current: 9.0.0
3434

3535
# Serverless
3636
serverless: *all
@@ -73,10 +73,10 @@ versioning_systems:
7373
# EDOTs
7474
edot-collector:
7575
base: 9.0
76-
current: 9.1.4
76+
current: 9.1.5
7777
edot-ios:
7878
base: 1.0
79-
current: 1.3.0
79+
current: 1.4.0
8080
edot-android:
8181
base: 1.0
8282
current: 1.2.0
@@ -85,16 +85,16 @@ versioning_systems:
8585
current: 1.1.0
8686
edot-java:
8787
base: 1.0
88-
current: 1.5.0
88+
current: 1.6.0
8989
edot-node:
9090
base: 1.0
91-
current: 1.4.0
91+
current: 1.5.0
9292
edot-php:
9393
base: 1.0
9494
current: 1.1.1
9595
edot-python:
9696
base: 1.0
97-
current: 1.8.0
97+
current: 1.9.0
9898
edot-cf-aws:
9999
base: 0.1
100100
current: 0.2.0

‎docs/_docset.yml‎

Lines changed: 63 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -46,26 +46,19 @@ toc:
4646
- file: branching-strategy.md
4747
- file: add-repo.md
4848
- file: release-new-version.md
49-
- folder: migration
49+
- folder: building-blocks
5050
children:
5151
- file: index.md
52-
- folder: freeze
53-
children:
54-
- file: index.md
55-
- file: gh-action.md
56-
- file: syntax.md
57-
- file: ia.md
58-
- file: versioning.md
59-
- file: engineering.md
60-
- folder: guide
61-
children:
62-
- file: index.md
63-
- file: working-in-docs-content.md
64-
- file: automated.md
65-
- file: tooling.md
66-
- file: move-ref-docs.md
67-
- file: mapping.md
68-
- file: how-to-set-up-docs-previews.md
52+
- file: documentation-set.md
53+
- file: assembled-documentation.md
54+
- file: distributed-documentation.md
55+
- file: link-service.md
56+
- file: link-index.md
57+
- file: link-catalog.md
58+
- file: outbound-cross-links.md
59+
- file: inbound-cross-links.md
60+
- file: documentation-set-navigation.md
61+
- file: global-navigation.md
6962
- folder: configure
7063
children:
7164
- file: index.md
@@ -74,9 +67,9 @@ toc:
7467
- file: index.md
7568
- file: content.md
7669
- file: navigation.md
70+
- file: products.md
7771
- file: versions.md
7872
- file: legacy-url-mappings.md
79-
- file: products.md
8073
- folder: content-set
8174
children:
8275
- file: index.md
@@ -121,6 +114,57 @@ toc:
121114
- file: tabs.md
122115
- file: tagged_regions.md
123116
- file: titles.md
117+
- folder: cli
118+
children:
119+
- file: index.md
120+
- folder: docset
121+
children:
122+
- file: index.md
123+
- file: build.md
124+
- file: diff-validate.md
125+
- file: index-command.md
126+
- file: mv.md
127+
- file: serve.md
128+
- folder: assembler
129+
children:
130+
- file: index.md
131+
- file: assemble.md
132+
- file: assembler-bloom-filter-create.md
133+
- file: assembler-bloom-filter-lookup.md
134+
- file: assembler-build.md
135+
- file: assembler-clone.md
136+
- file: assembler-config-init.md
137+
- file: assembler-content-source-match.md
138+
- file: assembler-content-source-validate.md
139+
- file: assembler-deploy-apply.md
140+
- file: assembler-deploy-plan.md
141+
- file: assembler-deploy-update-redirects.md
142+
- file: assembler-index.md
143+
- file: assembler-navigation-validate.md
144+
- file: assembler-navigation-validate-link-reference.md
145+
- file: assembler-serve.md
146+
- folder: links
147+
children:
148+
- file: index.md
149+
- file: inbound-links-validate.md
150+
- file: inbound-links-validate-all.md
151+
- file: inbound-links-validate-link-reference.md
152+
- folder: migration
153+
children:
154+
- file: index.md
155+
- file: syntax.md
156+
- file: ia.md
157+
- file: versioning.md
158+
- file: engineering.md
159+
- folder: guide
160+
children:
161+
- file: index.md
162+
- file: working-in-docs-content.md
163+
- file: automated.md
164+
- file: tooling.md
165+
- file: move-ref-docs.md
166+
- file: mapping.md
167+
- file: how-to-set-up-docs-previews.md
124168
# nested TOCs are only allowed from docset.yml by default
125169
# to prevent them from being nested deeply arbitrarily
126170
# use max_toc_depth to allow deeper nesting (Expert mode, consult with docs team)

‎docs/_redirects.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
redirects:
2+
'migration/freeze/gh-action.md' : 'index.md'
3+
'migration/freeze/index.md' : 'index.md'
24
'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
35
'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
46
'testing/redirects/6th-page.md':

‎docs/building-blocks/assembled-documentation.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
navigation_title: Assembled documentation
3+
---
4+
5+
# Assembled documentation
6+
7+
Assembled documentation is the product of building many [documentation sets](documentation-set.md) and weaving them into a global navigation to produce the fully assembled documentation site.
8+
9+
## How it works
10+
11+
The assembler:
12+
13+
1. Clones multiple documentation repositories.
14+
2. Reads the [configuration files](../configure/site/index.md) and builds [a global navigation](../configure/site/navigation.md).
15+
3. Builds each documentation set independently using the global configuration and navigation to inform path prefixes.
16+
4. Produces a unified documentation website.
17+
18+
## Configuration
19+
20+
Assembled documentation is configured through the site configuration, which defines:
21+
22+
* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md).
23+
* [navigation.yml](../configure/site/index.md): Navigation and url prefixes for TOC's.
24+
* [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented.
25+
* [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme.
26+
27+
Refer to [Site Configuration](../configure/site/index.md) for details on configuring assembled documentation.
28+
29+
:::{important}
30+
The `docs-builder` command makes no assumptions about how repositories, products, solutions and versions tie into each other.
31+
:::
32+
33+
## Build process
34+
35+
The typical build process for assembled documentation consists of three steps:
36+
37+
1. Clone all configured repositories using `docs-builder assembler clone`.
38+
2. Build all documentation sets using `docs-builder assembler build`.
39+
3. Serve the documentation on http://localhost:4000 using `docs-builder assembler serve`.
40+
41+
This uses the embedded configuration files inside the `docs-builder` binary. To build a specific configuration:
42+
43+
1. Fetch the latest config to `$(pwd)/config` `docs-builder assembler config init --local`.
44+
2. Clone all configured repositories using `docs-builder assembler clone --local`.
45+
3. Build all documentation sets using `docs-builder assembler build --local`.
46+
4. Serve the documentation on http://localhost:4000 using `docs-builder assembler serve`.
47+
48+
## Related concepts
49+
50+
* [Documentation Set](documentation-set.md): The individual units being assembled.
51+
* [Distributed Documentation](distributed-documentation.md): How documentation sets work independently.
52+
* [Link Catalog](link-catalog.md): How the assembler knows what to include.

0 commit comments

Comments
 (0)