Skip to content

Commit 4963f74

Browse files
bmorelli25bmorelli25
committed
add basic conversion doc
1 parent 62f580a commit 4963f74

File tree

8 files changed

+205
-68
lines changed

8 files changed

+205
-68
lines changed

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

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

3-
tbd
3+
Navigation is managed by a `docset.yml` file. This file has the following structure:
4+
5+
```yaml
6+
project: 'PROJECT_NAME'
7+
8+
external_hosts:
9+
- EXTERNAL_LINKS_HERE
10+
11+
exclude:
12+
- 'EXCLUDED_FILES'
13+
14+
toc:
15+
- file: index.md
16+
- folder: top-level-bucket-a
17+
children:
18+
- file: index.md
19+
- file: file-a.md
20+
- file: file-b.md
21+
- folder: top-level-bucket-b
22+
children:
23+
- file: index.md
24+
- folder: second-level-bucket-c
25+
children:
26+
- file: index.md
27+
```
28+
29+
## `project`
30+
31+
The name of the project.
32+
33+
Example:
34+
35+
```yaml
36+
project: 'APM Java agent reference'
37+
```
38+
39+
## `external_hosts`
40+
41+
All links to external hosts must be declared in this section of `docset.yml`.
42+
43+
Example:
44+
45+
```yaml
46+
external_hosts:
47+
- google.com
48+
- github.com
49+
```
50+
51+
## `exclude`
52+
53+
Files to exclude from the TOC. Supports glob patterns.
54+
55+
The following example excludes all markdown files beginning with `_`:
56+
57+
```yaml
58+
exclude:
59+
- '_*.md'
60+
```
61+
62+
## `toc`
63+
64+
Defines the table of contents (navigation) for the content set. A minimal toc is:
65+
66+
```yaml
67+
toc:
68+
- file: index.md
69+
```
70+
71+
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:
72+
73+
```yaml
74+
...
75+
- file: subsection/index.md
76+
children:
77+
- file: subsection/page-one.md
78+
- file: subsection/page-two.md
79+
```
80+
81+
```yaml
82+
...
83+
- folder: subsection
84+
children:
85+
- file: index.md
86+
- file: page-one.md
87+
- file: page-two.md
88+
```

‎docs/docset.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ toc:
4343
- folder: guide
4444
children:
4545
- file: index.md
46+
- file: automated.md
47+
- file: tooling.md
48+
- file: bug-bash.md
4649
- file: file-structure.md
4750
- file: mapping.md
4851
- folder: configure

‎docs/migration/guide/automated.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Migrate Automated Content to V3
2+
3+
If you have automated documentation in Asciidoc (or any other format) that you need to migrate to Elastic docs V3, this guide walks you through the essentials. Elastic docs V3 (powered by `docs-builder`) allows engineering teams to keep code and reference docs closely integrated for easier updates and greater accuracy.
4+
5+
## Minimum Viable Setup
6+
7+
You can build docs with `docs-builder` using just two files:
8+
9+
1. **`docset.yml`** — Configures the docset for `docs-builder`.
10+
2. **`index.md`** — A Markdown file that will be converted to HTML.
11+
12+
Once you have these files, follow the [Contribute Locally guide](../../contribute/locally.md) to get your docs building.
13+
14+
## Syntax
15+
16+
Elastic docs V3 fully supports [CommonMark](https://commonmark.org/) Markdown syntax. In addition, we support:
17+
18+
* Custom directives — our main extension point over markdown (learn more [here](../../syntax/md-extensions.md#directives))
19+
* A few GitHub flavored markdown extensions (see the list [here](../../syntax/md-extensions.md#github-flavored-markdown))
20+
21+
In most cases, plain Markdown covers basic needs, and directives add extra functionality as needed.
22+
23+
- At a minimum, each page must have an H1 heading:
24+
```markdown
25+
# I'm a heading
26+
```
27+
- You can optionally include [frontmatter](../../syntax/frontmatter.md) for additional metadata.
28+
29+
For more details on custom directives, see the [Syntax Guide](../../syntax/index.md).
30+
31+
## Navigation
32+
33+
Your `docset.yml` file configures how `docs-builder` handles navigation. Below is a minimal example:
34+
35+
```yaml
36+
project: 'PROJECT_NAME'
37+
38+
toc:
39+
- file: index.md
40+
```
41+
42+
For more information, see [Navigation](../../configure/content-set/navigation.md).
43+
44+
## Next steps
45+
46+
That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives.

‎docs/migration/guide/bug-bash.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Build migrated content sets for Bug Bashes
2+
3+
The following content sets are available for pre-migration testing:
4+
5+
* [elasticsearch.md](https://github.com/elastic/elasticsearch.md)
6+
* [integration-docs.md](https://github.com/elastic/integration-docs.md)
7+
* [kibana.md](https://github.com/elastic/kibana.md)
8+
* [logstash.md](https://github.com/elastic/logstash.md)
9+
* [machine-learning.md](https://github.com/elastic/machine-learning.md)
10+
* [observability-docs.md](https://github.com/elastic/observability-docs.md)
11+
12+
## Local directory structure
13+
14+
Assuming the following directory structure:
15+
16+
```markdown
17+
{GitHub_Repo_Dir}/
18+
├── tools/
19+
│ ├── docs-builder-mac-arm64.zip
20+
│ └── docs-builder
21+
├── elasticsearch.md
22+
├── observability-docs.md
23+
└── kibana.md
24+
```
25+
26+
You can build migrated content sets on a Mac by running the following commands.
27+
28+
```{tip}
29+
For other systems, see [Contribute locally](../../contribute/locally.md)
30+
```
31+
32+
```bash
33+
# move to GitHub dir
34+
cd {GitHub_Repo_Dir}
35+
36+
# clone req'd repos
37+
git clone https://github.com/elastic/elasticsearch.md.git
38+
git clone https://github.com/elastic/observability-docs.md.git
39+
git clone https://github.com/elastic/kibana.md.git
40+
41+
# move back to GitHub dir
42+
cd {GitHub_Repo_Dir}
43+
mkdir tools
44+
cd tools
45+
46+
# mac-specific
47+
curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
48+
unzip docs-builder-mac-arm64.zip
49+
50+
# Build ES Guide
51+
./docs-builder serve -p ../elasticsearch.md/docs
52+
53+
# Build Obs Guide
54+
./docs-builder serve -p ../observability-docs.md/docs
55+
56+
# Build Kib Guide
57+
./docs-builder serve -p ../kibana.md/docs
58+
```

‎docs/migration/guide/index.md‎

Lines changed: 4 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,7 @@
11
# Migration Guide
22

3-
How to migrate content from Asciidoc to V3.
3+
Migrate content from Asciidoc to V3
44

5-
## Migration tooling
6-
7-
Use the [adoc-to-md](https://github.com/elastic/adoc-to-md) conversion tool to migrate content sets from Asciidoc syntax to docs-builder syntax. Instructions to use the tool are in the readme file.
8-
9-
After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder.
10-
11-
## Building migrated content sets for the bug bash
12-
13-
Assuming the following directory structure:
14-
15-
```markdown
16-
{GitHub_Repo_Dir}/
17-
├── tools/
18-
│ ├── docs-builder-mac-arm64.zip
19-
│ └── docs-builder
20-
├── elasticsearch.md
21-
├── observability-docs.md
22-
└── kibana.md
23-
```
24-
25-
You can build migrated content sets on a Mac by running the following commands.
26-
27-
```{tip}
28-
For other systems, see [Contribute locally](../../contribute/locally.md)
29-
```
30-
31-
```bash
32-
# move to GitHub dir
33-
cd {GitHub_Repo_Dir}
34-
35-
# clone req'd repos
36-
git clone https://github.com/elastic/elasticsearch.md.git
37-
git clone https://github.com/elastic/observability-docs.md.git
38-
git clone https://github.com/elastic/kibana.md.git
39-
40-
# move back to GitHub dir
41-
cd {GitHub_Repo_Dir}
42-
mkdir tools
43-
cd tools
44-
45-
# mac-specific
46-
curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
47-
unzip docs-builder-mac-arm64.zip
48-
49-
# Build ES Guide
50-
./docs-builder serve -p ../elasticsearch.md/docs
51-
52-
# Build Obs Guide
53-
./docs-builder serve -p ../observability-docs.md/docs
54-
55-
# Build Kib Guide
56-
./docs-builder serve -p ../kibana.md/docs
57-
```
58-
59-
## Pre-migrated content sets available for testing:
60-
61-
* [elasticsearch.md](https://github.com/elastic/elasticsearch.md)
62-
* [integration-docs.md](https://github.com/elastic/integration-docs.md)
63-
* [kibana.md](https://github.com/elastic/kibana.md)
64-
* [logstash.md](https://github.com/elastic/logstash.md)
65-
* [machine-learning.md](https://github.com/elastic/machine-learning.md)
66-
* [observability-docs.md](https://github.com/elastic/observability-docs.md)
5+
* [Migrate automated documentation](./automated.md) — for developers
6+
* [Migrate narrative content manually](./tooling.md) — handled by the docs team
7+
* [Build pre-migrated content sets](./bug-bash.md) — for the docs team bug bash

‎docs/migration/guide/tooling.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Run migration tooling
2+
3+
Use the [adoc-to-md](https://github.com/elastic/adoc-to-md) conversion tool to migrate content sets from Asciidoc syntax to docs-builder syntax. Instructions to use the tool are in the readme file.
4+
5+
After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder.

‎docs/syntax/frontmatter.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,5 @@ Supported frontmatter includes:
66

77
| Frontmatter | Learn more |
88
| ------------------- | --------------------------- |
9-
| `title` | See [title](./titles.md) |
109
| `navigation_title` | See [title](./titles.md) |
1110
| `applies` | See [product availability](./applies.md) |

‎docs/syntax/titles.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ Each page is required to at least define a level one heading.
1414

1515
This title is used both by the documentation navigation
1616

17-
* Left hand site
17+
* Left hand site
1818
* Navigational elements such as breadcrumbs and previous/next links.
1919

20-
As well as when using the autolink naming feature e.g:
20+
As well as when using the [auto text links](./links.md#auto-text-links), e.g:
2121

2222
```markdown
23-
[titles.md]()
23+
[](titles.md)
2424
```
2525

2626
Generated link text: [](titles.md)

0 commit comments

Comments
 (0)