|
| 1 | +--- |
| 2 | +navigation_title: assembler.yml |
| 3 | +--- |
| 4 | + |
1 | 5 | # `assembler.yml` |
2 | 6 |
|
3 | | -The global navigation is defined in the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file. This file can roughly be thought of as the V3 equivalent of conf.yaml in the asciidoc build system. This file, which writers own, allows for arbitrary nesting of `docset.yml` and `toc.yml` references. This file will live in the `elastic/docs-content` repository, but will not build or have any influence over the `docs-builder` builds in that repo. |
| 7 | +The [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file defines the global documentation site: |
4 | 8 |
|
5 | | -The global navigation that is defined in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) can be composed of three main resources: |
6 | | -1. Local TOC files: toc.yml files that live in the docs-content repository. |
7 | | -2. External TOC files: A subset of a content set (represented by a toc.yml file) that is external to the docs-content repository. |
8 | | -3. External content set declarations: An entire docset.yml file that is external to the docs-content repository. |
| 9 | +* `environments` |
| 10 | +* `shared_configuration` |
| 11 | +* narrative repository configuration |
| 12 | +* reference repository configurations |
9 | 13 |
|
10 | | -The [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file might look something like this: |
| 14 | +## `environments` |
11 | 15 |
|
12 | | -```yaml |
| 16 | +This section defines different build environments for the documentation site. |
| 17 | + |
| 18 | +Each environment specifies configuration details such as the site URI, content source, path prefix, Google Tag Manager settings, and feature flags. |
| 19 | + |
| 20 | +Example: |
| 21 | + |
| 22 | +```yml |
| 23 | +environments: |
| 24 | + prod: |
| 25 | + uri: https://www.elastic.co |
| 26 | + path_prefix: docs |
| 27 | + content_source: current |
| 28 | + allow_indexing: true |
| 29 | + google_tag_manager: |
| 30 | + enabled: true |
| 31 | + id: GTM-KNJMG2M |
| 32 | +``` |
| 33 | +
|
| 34 | +## `shared_configuration` |
13 | 35 |
|
| 36 | +This section defines YAML anchors for common settings shared among multiple repositories and deployment environments. |
| 37 | + |
| 38 | +The following example sets a unique `stack` version for each of the three defined deployment environments: |
| 39 | + |
| 40 | +```yml |
| 41 | + stack: &stack |
| 42 | + current: 9.0 |
| 43 | + next: 9.1 |
| 44 | + edge: main |
14 | 45 | ``` |
15 | 46 |
|
16 | | -## Assembler constraints |
| 47 | +## `narrative` |
17 | 48 |
|
18 | | -To maintain each docset’s immutability and self-containment, resources in the global navigation (assembler.yml) must follow specific rules. |
19 | | -1. A link resource can appear only once in the global navigation, and it must nest directly under another resource (not under individual pages from a different content set). In other words: |
20 | | - 1. Each docset.yml or toc.yml file can appear only once in the overall navigation. |
21 | | - 1. Any TOC declarations—whether in docset.yml or toc.yml—must be placed either at the top level or directly under another TOC entry, with no individual files in between. |
22 | | -1. Nested resources must appear either before or after (default) the parent’s TOC, and they cannot be placed arbitrarily among the parent’s pages (e.g., between two files of the parent). |
23 | | -1. If an external TOC is linked, all of its child TOCs must also be included in the global navigation. |
| 49 | +Configures the main `docs-content` repository. |
24 | 50 |
|
25 | | -## AsciiDoctor conf.yml |
| 51 | +Example: |
| 52 | + |
| 53 | +```yml |
| 54 | +narrative: |
| 55 | + checkout_strategy: full |
| 56 | +``` |
26 | 57 |
|
27 | | -In the AsciiDoctor-powered site, content configuration at the site level is done in the [`conf.yaml`](https://github.com/elastic/docs/blob/master/conf.yaml) file in the elastic/docs repo. In the `conf.yml` file, the configuration information for all books are listed in this one file. Here's the example of what it looks like to configure a single book: |
| 58 | +## `references` |
| 59 | + |
| 60 | +Configures all other repositories whose docs content should be included or referenced in the build. Each can have custom settings for branch, checkout method, etc. |
| 61 | + |
| 62 | +Example: |
| 63 | + |
| 64 | +```yml |
| 65 | +references: |
| 66 | + apm-server: |
| 67 | +``` |
| 68 | + |
| 69 | +### Branching strategy |
| 70 | + |
| 71 | +How you add a reference repository depends on its [branching strategy](../content-sources.md#branching-strategies). |
| 72 | + |
| 73 | +#### Continuous deployment repository |
| 74 | + |
| 75 | +To add a continuous deployment repository, define the name of the repository: |
28 | 76 |
|
29 | 77 | ```yaml |
30 | | -- title: Machine Learning |
31 | | - prefix: en/machine-learning |
32 | | - current: *stackcurrent |
33 | | - index: docs/en/stack/ml/index.asciidoc |
34 | | - branches: [ {main: master}, 8.9, 8.8, 8.7, 8.6, 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3 ] |
35 | | - live: *stacklive |
36 | | - chunk: 1 |
37 | | - tags: Elastic Stack/Machine Learning |
38 | | - subject: Machine Learning |
39 | | - sources: |
40 | | - - |
41 | | - repo: stack-docs |
42 | | - path: docs/en/stack |
43 | | - - |
44 | | - repo: elasticsearch |
45 | | - path: docs |
46 | | - - |
47 | | - repo: docs |
48 | | - path: shared/versions/stack/{version}.asciidoc |
49 | | - - |
50 | | - repo: docs |
51 | | - path: shared/attributes.asciidoc |
52 | | - - |
53 | | - repo: docs |
54 | | - path: shared/settings.asciidoc |
| 78 | +references: |
| 79 | + my-repository: |
55 | 80 | ``` |
| 81 | + |
| 82 | +The above configuration is equivalent to specifying. |
| 83 | + |
| 84 | +```yaml |
| 85 | +references: |
| 86 | + my-repository: |
| 87 | + next: main |
| 88 | + current: main |
| 89 | +``` |
| 90 | + |
| 91 | +### Tagged repository |
| 92 | + |
| 93 | +To add a tagged repository, configure the repo to have a fixed git reference (typically a branch) deploy the `current` content source to production. |
| 94 | + |
| 95 | +```yaml |
| 96 | +references: |
| 97 | + my-other-repository: |
| 98 | + next: main |
| 99 | + current: 9.0 |
| 100 | +``` |
0 commit comments