Skip to content

Commit 8e444d7

Browse files
bmorelli25bmorelli25
authored
Add basic content on what's needed to build docs with docs-builder (#338)
* add basic conversion doc * add more updates * add migration tooling docs
1 parent 30e0d03 commit 8e444d7

19 files changed

+404
-133
lines changed

‎docs/configure/content-set/attributes.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,25 @@
11
# Attributes
22

3-
tbd
3+
To promote consistency across documentation, AsciiDoc uses shared attributes for common terms, URLs, and versions.
4+
5+
In the AsciiDoctor-based system, shared attributes are defined at the site-level and live in the [`shared/` directory](https://github.com/elastic/docs/blob/master/shared) in the elastic/docs repo. The most used files in this directory are:
6+
7+
* The [`attributes.asciidoc` file](https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc), which contains URLs, common words and phrases, and more.
8+
* The files in the [`versions/stack` directory](https://github.com/elastic/docs/tree/master/shared/versions/stack), which contain the latest versions for various products for a given Stack version.
9+
10+
## In `docs-builder`
11+
12+
Attributes are defined at the content set-level. Use the `subs` key to define attributes as key-value pairs in the content sets `docset.yml` or `toc.yml` file.
13+
14+
Example:
15+
16+
```yml
17+
subs:
18+
attr-name: "attr value"
19+
ea: "Elastic Agent"
20+
es: "Elasticsearch"
21+
```
22+
23+
## Use attributes
24+
25+
Attributes can be referenced in documentation file with the following syntax: `{{attr-name-here}}`.

‎docs/configure/content-set/file-structure.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
11
# File structure
22

3-
tbd
3+
The file structure of each content set directly impacts the url path structure of each page. In other words, the directory structure you pull into docs-builder is the same as the directory structure it spits out.
4+
5+
## Navigation
6+
7+
Navigation is set independent of directory and file structure in docset and toc files.
8+
9+
See [Navigation](./navigation.md) to learn more.

‎docs/configure/content-set/index.md

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,20 @@
11
---
2-
navigation_title: Content set
2+
navigation_title: Content set-level
33
---
44

5-
# Content set configuration
5+
# Content set-level configuration
66

7-
Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: content sets. At the book level, the system consists of:
7+
Elastic documentation is spread across multiple repositories. Each repository can contain one or more content sets. A content set is a group of documentation pages whose navigation is defined by a single `docset.yml` file. `docs-builder` builds each content set in isolation, ensuring that changes in one repository don’t affect another.
8+
9+
A content set in `docs-builder` is equivalent to an AsciiDoc book. At this level, the system consists of:
810

911
| System property | Asciidoc | V3 |
1012
| -------------------- | -------------------- | -------------------- |
1113
| **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams |
12-
| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | TBD |
14+
| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | `docset.yml` and/or `toc.yml` file(s) |
15+
16+
## Learn more
17+
18+
* [File structure](./file-structure.md)
19+
* [Navigation](./navigation.md)
20+
* [Attributes](./attributes.md)

‎docs/configure/content-set/navigation.md

Lines changed: 123 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,125 @@
11
# Navigation
22

3-
tbd
3+
Two types of nav files are supported: `docset.yml` and `toc.yml`.
4+
5+
## `docset.yml`
6+
7+
Example:
8+
9+
```yaml
10+
project: 'PROJECT_NAME'
11+
12+
external_hosts:
13+
- EXTERNAL_LINKS_HERE
14+
15+
exclude:
16+
- 'EXCLUDED_FILES'
17+
18+
toc:
19+
- file: index.md
20+
- toc: elastic-basics
21+
- folder: top-level-bucket-a
22+
children:
23+
- file: index.md
24+
- file: file-a.md
25+
- file: file-b.md
26+
- folder: top-level-bucket-b
27+
children:
28+
- file: index.md
29+
- folder: second-level-bucket-c
30+
children:
31+
- file: index.md
32+
```
33+
34+
### `project`
35+
36+
The name of the project.
37+
38+
Example:
39+
40+
```yaml
41+
project: 'APM Java agent reference'
42+
```
43+
44+
### `external_hosts`
45+
46+
All links to external hosts must be declared in this section of `docset.yml`.
47+
48+
Example:
49+
50+
```yaml
51+
external_hosts:
52+
- google.com
53+
- github.com
54+
```
55+
56+
### `exclude`
57+
58+
Files to exclude from the TOC. Supports glob patterns.
59+
60+
The following example excludes all markdown files beginning with `_`:
61+
62+
```yaml
63+
exclude:
64+
- '_*.md'
65+
```
66+
67+
### `toc`
68+
69+
Defines the table of contents (navigation) for the content set. A minimal toc is:
70+
71+
```yaml
72+
toc:
73+
- file: index.md
74+
```
75+
76+
The table of contents can be created independent of the directory structure of the files it defines. You can use directories to define nesting in the TOC, but you don't have to. For example, both of the following create the same nav structure:
77+
78+
```yaml
79+
...
80+
- file: subsection/index.md
81+
children:
82+
- file: subsection/page-one.md
83+
- file: subsection/page-two.md
84+
```
85+
86+
```yaml
87+
...
88+
- folder: subsection
89+
children:
90+
- file: index.md
91+
- file: page-one.md
92+
- file: page-two.md
93+
```
94+
95+
#### Nest `toc`
96+
97+
The `toc` key can include nested `toc.yml` files.
98+
99+
The following example includes two sub-`toc.yml` files located in directories named `elastic-basics` and `solutions`:
100+
101+
```yml
102+
toc:
103+
- file: index.md
104+
- toc: elastic-basics
105+
- toc: solutions
106+
```
107+
108+
### Attributes
109+
110+
Example:
111+
112+
```yml
113+
subs:
114+
attr-name: "attr value"
115+
ea: "Elastic Agent"
116+
es: "Elasticsearch"
117+
```
118+
119+
See [Attributes](./attributes.md) to learn more.
120+
121+
## `toc.yml`
122+
123+
As a rule, each `docset.yml` file can only be included once in the assembler. This prevents us from accidentally duplicating pages in the docs. However, there are times when you want to split content sets and include them partially in different areas of the TOC. That's what `toc.yml` files are for. These files split one documentation set into multiple “sub-TOCs,” each mapped to a different navigation node.
124+
125+
All configuration options that `docset.yml` supports are supported by `toc.yml`.

‎docs/configure/index.md

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,40 @@ navigation_title: Configuration reference
44

55
# Configure Elastic Docs
66

7-
* [Page configuration](./page.md)
8-
* [Content-set configuration](./content-set/index.md)
9-
* [Site configuration](./site/index.md)
7+
It's first important to understand how we build Elastic Docs:
8+
9+
| System property | Asciidoc | V3 |
10+
| -------------------- | -------------------- | -------------------- |
11+
| **Docs build tool** --> An engine used to take the markup in the content sources and transform it into web pages. | Customized version of AsciiDoctor (lives in [**elastic/docs**](https://github.com/elastic/docs)) | Customized doc builder using open source tools (lives in [**elastic/docs-builder**](https://github.com/elastic/docs-builder)) |
12+
13+
When working with `docs-builder`, there are three levels at which you can configure Elastic documentation:
14+
15+
1. Site-level
16+
2. Content set-level
17+
3. Page-level
18+
19+
## Site-level configuration
20+
21+
At the site level, you can configure:
22+
23+
* Content sources: where files live
24+
* Global navigation: how navigations are compiled and presented to users
25+
26+
[Site configuration](./site/index.md)
27+
28+
## Content-level configuration
29+
30+
At the content set level, you can configure:
31+
32+
* Content-set-level and sub-content-set-level navigation: how smaller groups of files are organized and presented to users
33+
* Attributes: variables that will be substituted at build-time for pre-defined values
34+
35+
[Content-set configuration](./content-set/index.md)
36+
37+
## Page-level configuration
38+
39+
At the page level, you can configure:
40+
41+
* Frontmatter that influences on-page UX to benefit the user in some way
42+
43+
[Page configuration](./page.md)

‎docs/configure/page.md

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
11
---
2-
navigation_title: Page
2+
navigation_title: Page-level
33
---
44

5-
# Page configuration
5+
# Page-level configuration
66

7-
tbd
8-
9-
go into frontmatter here?
10-
11-
for now, see [frontmatter](../syntax/frontmatter.md).
7+
For now, page configuration is minimal. See [frontmatter](../syntax/frontmatter.md) for supported options.

‎docs/configure/site/content.md

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,26 @@
1-
# Content config
1+
# `assembler.yml`
22

3-
In both the AsciiDoctor- and V3-based system, there is site-wide configuration where you list all content sources, where to find those sources, and in what order they should be added to the site.
3+
The global navigation is defined in the `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.
44

5-
In the AsciiDoctor system, this all happens in one YAML file in the /docs repo. In the V3 system, this ...
5+
The global navigation that is defined in `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+
10+
The `assembler.yml` file might look something like this:
11+
12+
```yaml
13+
14+
```
15+
16+
## Assembler constraints
17+
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.
624

725
## AsciiDoctor conf.yml
826

@@ -35,7 +53,3 @@ In the AsciiDoctor-powered site, content configuration at the site level is done
3553
repo: docs
3654
path: shared/settings.asciidoc
3755
```
38-
39-
## V3 configuration
40-
41-
TO DO

‎docs/configure/site/index.md

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,42 @@
11
---
2-
navigation_title: Site
2+
navigation_title: Site-level
33
---
44

5-
# Site configuration
6-
7-
Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. The system consists of:
5+
# Site-level configuration
86

7+
Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. At the site-level, we have:
98

109
| System property | Asciidoc | V3 |
1110
| -------------------- | -------------------- | -------------------- |
1211
| **Content sources** --> Collections of markup files containing doc content. These are split up across many docs repos. | _Books_ | _Content sets_ |
13-
| **Content configuration** --> A way to specify where to find those content sources, and in what order they should be added to the site. | Configuration file ([`conf.yml`](https://github.com/elastic/docs/blob/master/conf.yaml) in elastic/docs) | Config file location TBD |
14-
| **Cross-site values** --> Key-value pairs that should be substituted across all sources as web pages are built. | Shared attributes ([`shared/`](https://github.com/elastic/docs/tree/master/shared) in elastic/docs) | Shared attrs file TBD |
15-
| **Docs build tool** --> An engine used to take the markup in the content sources and transform it into web pages. | Customized version of AsciiDoctor (lives in [**elastic/docs**](https://github.com/elastic/docs)) | Customized doc builder using open source tools (lives in [**elastic/docs-builder**](https://github.com/elastic/docs-builder)) |
12+
| **Content configuration** --> A way to specify where to find those content sources, and in what order they should be added to the site. | Configuration file ([`conf.yml`](https://github.com/elastic/docs/blob/master/conf.yaml) in elastic/docs) | Config file `assembler.yml` |
1613

1714
Where these pieces live and what format they are in varies between the two systems, but they generally achieve the same goal.
1815

19-
## Asciidoc
16+
## Content sources
2017

21-
![site-level config in the asciidoc system](./img/site-level-asciidoctor.png)
18+
TBD
19+
20+
## Content configuration
21+
22+
In both the AsciiDoctor- and V3-based system, there is site-wide configuration where you list all content sources, where to find those sources, and in what order they should be added to the site.
23+
24+
In the AsciiDoctor system, this all happens in one YAML file in the `/docs` repo. In the V3 system, this happens in the `assembler.yml` file in `docs-content`.
25+
26+
[assembler.yml](./content.md)
27+
28+
## Landing page
2229

23-
## V3
30+
See [landing page](./landing-page.md)
2431

25-
DIAGRAM NEEDED
32+
## Redirects
33+
34+
Plan still needed
35+
36+
## V3 site-level diagram
37+
38+
DIAGRAM NEEDED
39+
40+
## Asciidoc site-level diagram
41+
42+
![site-level config in the asciidoc system](./img/site-level-asciidoctor.png)

‎docs/configure/site/landing-page.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# Landing page
22

3-
tbd
3+
The landing page will initially be an HTML template. To update the landing page, you will directly edit the HTML template. Eventually, we will templetize the landing page for easier updates.

‎docs/configure/site/redirects.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ STRATEGY TBD
1818

1919
## Migration redirects
2020

21-
Docs inventory script: https://github.com/elastic/docs-helpers/tree/main/docs-inventory
22-
Docs inventory sheet: https://docs.google.com/spreadsheets/d/1LfPI3TZqdpONGxOmL8B8V-Feo1flLwObz9_ibCEMkIQ/edit?gid=605983744#gid=605983744
21+
* Docs inventory script: https://github.com/elastic/docs-helpers/tree/main/docs-inventory
22+
* Docs inventory sheet: https://docs.google.com/spreadsheets/d/1LfPI3TZqdpONGxOmL8B8V-Feo1flLwObz9_ibCEMkIQ/edit?gid=605983744#gid=605983744
2323

2424
This sheet will be used to request redirects after migration from 8.current to 9.current.

0 commit comments

Comments
 (0)