Skip to content

Commit a3c2e6d

Browse files
bmorelli25bmorelli25
committed
add configure, contribution, and migration guides
1 parent ff0bb49 commit a3c2e6d

File tree

9 files changed

+113
-8
lines changed

9 files changed

+113
-8
lines changed

‎docs/source/configure/img/site-level-asciidoctor.png‎

176 KB
Loading

‎docs/source/configure/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Configure Elastic Docs
3+
navigation_title: Configuration reference
4+
---

‎docs/source/configure/page-level.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Page configuration
3+
navigation_title: Page
4+
---

‎docs/source/configure/site-level.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Site configuration
3+
navigation_title: Site
4+
---
5+
6+
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:
7+
8+
9+
| System property | Asciidoc | V3 |
10+
| -------------------- | -------------------- | -------------------- |
11+
| **Content sources** --> Collections of markup files containing doc content. These are split up across many docs repos. | _Books_ | _Content sets_ |
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 location TBD |
13+
| **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 |
14+
| **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)) |
15+
16+
## Asciidoc
17+
18+
![site-level config in the asciidoc system](./img/site-level-asciidoctor.png)

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
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

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
---
2+
title: Update the docs in your web browser
3+
---

‎docs/source/contribute/index.md‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,8 @@ title: Elastic Docs contribution guide
33
navigation_title: Contribution guide
44
---
55

6-
Want to contribute to the Elastic documentation? You're in the right spot!
6+
Want to contribute to the Elastic documentation? You're in the right spot! Select an option below to get started:
77

8-
1. Install dependencies
9-
2. Clone repositories
10-
3. Make changes
11-
4. Open a Pull Request
12-
5. Work with CI
13-
6. Get approvals and merge
14-
7. View your changes live on elastic.co
8+
* I just want to suggest a change --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml)
9+
* I want to make a small change to a single page --> [Update the docs in your _web browser_](change-browser.md).
10+
* I want to make a larger change or a change to multiple pages --> [Update the docs in your _code editor_](change-local.md).

‎docs/source/docset.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,17 @@ toc:
2222
- folder: migration
2323
children:
2424
- file: index.md
25+
- file: file-structure.md
2526
- folder: contribute
2627
children:
2728
- file: index.md
29+
- file: change-browser.md
30+
- file: change-local.md
31+
- folder: configure
32+
children:
33+
- file: index.md
34+
- file: page-level.md
35+
- file: site-level.md
2836
- folder: syntax
2937
children:
3038
- file: index.md

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: File structure
3+
---
4+
5+
In both the AsciiDoc- and V3-based systems, file structure is largely independent from the resulting site navigation.
6+
7+
## File and directory structure
8+
9+
AsciiDoc files and assets (like images and videos) can be stored anywhere within the directories provided as `sources` for a given book in the central [`config.yaml` file in the /docs repo](https://github.com/elastic/docs/blob/master/conf.yaml).
10+
11+
## Migration tool output
12+
13+
The migration tool will add all MD files in a single directory. There will be one MD file for each web page in the migrated book. The name of each MD file and the URL in the new docs system are both derived from the URL of the AsciiDoc-built page.
14+
15+
**Example:** Here's what happens with the
16+
[Spans](https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html) page
17+
in the APM docs:
18+
19+
* **Old URL**: The URL for the page in the old system is:
20+
`https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html`.
21+
From the URL, we can determine the:
22+
* _base URL_: `https://www.elastic.co/guide`
23+
* _book ID_: `en/apm/guide`
24+
* _version_: `current`
25+
* _page ID_: `data-model-spans`
26+
* **New filename**: The page ID determines the filename of the migrated MD file:
27+
% `data-model-spans.mdx`. This file will be in the root directory of the directory containing the content for the `en/apm/guide` book.
28+
* **New URL**: The new URL for this page in the new docs system will be `xxxx`.
29+
*
30+
Because a single AsciiDoc file can contain the content for multiple pages (or content
31+
displayed on a single page could be spread across multiple AsciiDoc files), the `.asciidoc`
32+
filename can be different than the `.md` filename. However, you should be able to locate
33+
the source content if you know which web page it lives on.
34+
35+
In the output from the migration tool the slug (for example, `en/apm/guide/data-model-spans`)
36+
and the MD filename (for example, `data-model-spans.md`) are both derived from
37+
the page ID, they don't _have_ to be the same.
38+
39+
### Assets
40+
41+
The migration tool creates an `images/` directory in the base directory for the doc set.
42+
Inside the `images/` directory, there is subdirectory for each page ID that contains images.
43+
44+
For example, the images that are used on the [Entity Analytics dashboard](https://www.elastic.co/guide/en/security/current/detection-entity-dashboard.html) page in the AsciiDoc Security book would be copied to
45+
the following location in the migrated docs:
46+
47+
```
48+
images
49+
└─ detection-entity-dashboard
50+
├─ dashboards-anomalies-table.png
51+
├─ dashboards-entity-dashboard.png
52+
├─ dashboards-host-score-data.png
53+
├─ dashboards-run-job.png
54+
└─ dashboards-user-score-data.png
55+
```
56+
57+
These can be reorganized post-migration.
58+
59+
### Reusable content
60+
61+
Reusable content is lost during migration.

0 commit comments

Comments
 (0)