Skip to content

Commit 470dba0

Browse files
leemthompoleemthompo
committed
Restore syntax files and contribute guides to docs-builder
Simplified migration scope means most content stays in docs-builder. Only migrating quick-ref, locally.md, on-the-web.md, and cumulative-docs. Restored: - All syntax files (33+ pages) except quick-ref.md - move.md and redirects.md in contribute folder Keeping soft redirects for: - syntax/quick-ref.md - contribute/locally.md - contribute/on-the-web.md - contribute/cumulative-docs/ (index.md already has redirect)
1 parent ce24840 commit 470dba0

35 files changed

+4467
-5
lines changed

‎docs/contribute/move.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,31 @@
11
# Move files and folders
22

3-
:::{note}
4-
👋 This page has moved to [elastic.co/docs](https://www.elastic.co/docs/contribute-docs/how-to/move).
3+
When you move a source file or folder, you must also update all inbound and outbound links to reflect the new file location. `docs-builder` provides tooling to handle this step for you.
4+
5+
## `docs-builder mv`
6+
7+
Move a file or folder from one location to another and update all links in the documentation. For example:
8+
9+
```bash
10+
docs-builder mv ./old-location/ia.md ./new-location/ia.md
11+
```
12+
13+
:::{important}
14+
The `docset.yml` and `toc.yml` files are not automatically updated when using this tool. You must update these references manually.
515
:::
16+
17+
## `docs-builder mv --help`
18+
19+
```bash
20+
Usage: mv [arguments...] [options...] [-h|--help] [--version]
21+
22+
Move a file or folder from one location to another and update all links in the documentation
23+
24+
Arguments:
25+
[0] <string?> The source file or folder path to move from
26+
[1] <string?> The target file or folder path to move to
27+
28+
Options:
29+
--dry-run <bool?> Dry run the move operation (Default: null)
30+
-p|--path <string?> Defaults to the`{pwd}` folder (Default: null)
31+
```

‎docs/contribute/redirects.md‎

Lines changed: 190 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,192 @@
1+
---
2+
navigation_title: "Redirects"
3+
---
4+
15
# Manage redirects across doc sets
26

3-
:::{note}
4-
👋 This page has moved to [elastic.co/docs](https://www.elastic.co/docs/contribute-docs/how-to/redirects).
5-
:::
7+
When you [move](move.md) or delete pages, other [documentation sets](../configure/content-set/index.md) might still link to them. This can lead to a chicken-and-egg problem: you can't publish your changes without breaking links elsewhere.
8+
9+
Redirects let you map old links to new targets across documentation sets, so you can publish changes while updating other doc sets.
10+
11+
## Limitations
12+
13+
Redirects only work within Elastic Docs V3 content sets. You cannot use this method to redirect to external destinations like [API docs](https://www.elastic.co/docs/api/).
14+
15+
For API redirects, consult with the documentation engineering team on Slack (#elastic-docs-v3).
16+
17+
For elastic.co/guide redirects, open a [web team request](http://ela.st/web-request).
18+
19+
## Add a redirect
20+
21+
To successfully implement a redirect:
22+
23+
1. Locate and open the `redirects.yml` file to edit.
24+
- Each docs repository powered by Docs V3 can have its own `redirects.yml` file. You must only edit the one in the repository that you're moving or removing files from.
25+
- It is at the same location as the `docset.yml` file. Depending on the repository, this is generally at the root or within the `/docs` folder of the repository.
26+
27+
:::{note}
28+
Some repositories might not yet have a `redirects.yml` file. In this case, create one next to the repo's `docset.yml` file. Refer to [](#file-location).
29+
:::
30+
31+
2. Edit the file. Refer to [](#syntax) to get details on the expected syntax.
32+
- All paths must be relative to the `redirects.yml` file.
33+
- You may need to adjust the syntax based on how you'd like to treat anchors within redirected files. Find examples in [](#syntax).
34+
35+
3. Fix all existing links to the moved or removed file within the repository where you're adding the redirect, by updating them to the new correct target, or by removing them if necessary. This is a best practice to keep our content healthy, and mandatory for your PR to pass CI checks.
36+
37+
4. Create a PR with all of the changes made through the previous steps.
38+
39+
CI checks run to validate the newly added redirect and the docs build.
40+
If you get validation errors about the redirect, double check that your changes follow all the steps in this procedure. If the errors persist after a writer reviewed the PR, ask @elastic/docs-engineering for assistance.
41+
42+
## Validation
43+
44+
Running `docs-builder diff validate` will give you feedback on whether all necessary redirect rules are in place after your changes. It will also run on pull requests.
45+
46+
## File location
47+
48+
Redirects are configured at the content set-level.
49+
The configuration file should be located next to your `docset.yml` file:
50+
51+
* `redirects.yml` if you use `docset.yml`
52+
* `_redirects.yml` if you use `_docset.yml`
53+
54+
## Syntax
55+
56+
Example syntax:
57+
58+
```yaml
59+
redirects:
60+
'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
61+
'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
62+
'testing/redirects/6th-page.md':
63+
'testing/redirects/7th-page.md':
64+
to: 'testing/redirects/5th-page.md'
65+
anchors: '!'
66+
'testing/redirects/first-page-old.md':
67+
to: 'testing/redirects/second-page.md'
68+
anchors:
69+
'old-anchor': 'active-anchor'
70+
'removed-anchor':
71+
'testing/redirects/second-page-old.md':
72+
many:
73+
- to: "testing/redirects/second-page.md"
74+
anchors:
75+
"aa": "zz"
76+
"removed-anchor":
77+
- to: "testing/redirects/third-page.md"
78+
anchors:
79+
"bb": "yy"
80+
'testing/redirects/third-page.md':
81+
anchors:
82+
'removed-anchor':
83+
'testing/redirects/cross-repo-page.md': 'other-repo://reference/section/new-cross-repo-page.md'
84+
'testing/redirects/8th-page.md':
85+
to: 'other-repo://reference/section/new-cross-repo-page.md'
86+
anchors: '!'
87+
many:
88+
- to: 'testing/redirects/second-page.md'
89+
anchors:
90+
'item-a': 'yy'
91+
- to: 'testing/redirects/third-page.md'
92+
anchors:
93+
'item-b':
94+
95+
96+
```
97+
98+
### Redirect preserving all anchors
99+
100+
This example redirects `4th-page.md#anchor` to `5th-page.md#anchor`:
101+
102+
```yaml
103+
redirects:
104+
'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
105+
```
106+
### Redirect stripping all anchors
107+
108+
This example strips all anchors from the source page.
109+
Any remaining links resolving to anchors on `7th-page.md` will fail link validation.
110+
111+
```yaml
112+
redirects:
113+
'testing/redirects/7th-page.md':
114+
to: 'testing/redirects/5th-page.md'
115+
anchors: '!'
116+
```
117+
118+
Alternate syntax:
119+
120+
```yaml
121+
redirects:
122+
'testing/redirects/7th-page.md': '!testing/redirects/5th-page.md'
123+
```
124+
125+
To handle removed anchors on a page that still exists, omit the `to:` field:
126+
127+
```yaml
128+
'testing/redirects/third-page.md':
129+
anchors:
130+
'removed-anchor':
131+
```
132+
133+
### Redirect with renamed anchors
134+
135+
This example redirects:
136+
137+
- `first-page-old.md#old-anchor` → `second-page.md#active-anchor`
138+
- `first-page-old.md#removed-anchor` → `second-page.md`
139+
- Any other anchor is passed through and validated normally.
140+
141+
```yaml
142+
redirects:
143+
'testing/redirects/first-page-old.md':
144+
to: 'testing/redirects/second-page.md'
145+
anchors:
146+
'old-anchor': 'active-anchor'
147+
'removed-anchor':
148+
```
149+
150+
### Redirecting to other repositories
151+
152+
Use the `repo://path/to/page.md` syntax to redirect across repositories.
153+
154+
```yaml
155+
redirects:
156+
'testing/redirects/cross-repo-page.md': 'other-repo://reference/section/new-cross-repo-page.md'
157+
```
158+
159+
### Managing complex scenarios with anchors
160+
161+
* `to`, `anchor` and `many` can be used together to support more complex scenarios.
162+
* Setting `to` at the top level determines the default case, which can be used for partial redirects.
163+
* Cross-repository links are supported, with the same syntax as in the previous example.
164+
* The existing rules for `anchors` also apply here. To define a catch-all redirect, use `{}`.
165+
166+
```yaml
167+
redirects:
168+
# In this first scenario, the default redirection target remains the same page, with anchors being preserved.
169+
# Omitting the ``anchors`` tag or explicitly setting it as empty are both supported.
170+
'testing/redirects/8th-page.md':
171+
to: 'testing/redirects/8th-page.md'
172+
many:
173+
- to: 'testing/redirects/second-page.md'
174+
anchors:
175+
'item-a': 'yy'
176+
- to: 'testing/redirects/third-page.md'
177+
anchors:
178+
'item-b':
179+
180+
# In this scenario, the default redirection target is a different page, and anchors are dropped.
181+
'testing/redirects/deleted-page.md':
182+
to: 'testing/redirects/5th-page.md'
183+
anchors: '!'
184+
many:
185+
- to: "testing/redirects/second-page.md"
186+
anchors:
187+
"aa": "zz"
188+
"removed-anchor":
189+
- to: "other-repo://reference/section/partial-content.md"
190+
anchors:
191+
"bb": "yy"
192+
```

‎docs/syntax/admonitions.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Admonitions
2+
3+
Admonitions allow you to highlight important information with varying levels of priority. In software documentation, these blocks are used to emphasize risks, provide helpful advice, or share relevant but non-critical details.
4+
5+
## Basic admonitions
6+
7+
Admonitions can span multiple lines and support inline formatting.
8+
Available admonition types include:
9+
10+
- [Note](#note)
11+
- [Warning](#warning)
12+
- [Tip](#tip)
13+
- [Important](#important)
14+
- [Plain](#plain)
15+
16+
### Note
17+
18+
A relevant piece of information with no serious repercussions if ignored.
19+
20+
21+
:::::{tab-set}
22+
23+
::::{tab-item} Output
24+
25+
:::{note}
26+
This is a note.
27+
It can span multiple lines and supports inline formatting.
28+
:::
29+
30+
::::
31+
32+
::::{tab-item} Markdown
33+
34+
```markdown
35+
:::{note}
36+
This is a note.
37+
It can span multiple lines and supports inline formatting.
38+
:::
39+
```
40+
41+
::::
42+
43+
:::::
44+
45+
### Warning
46+
47+
You could permanently lose data or leak sensitive information.
48+
49+
:::::{tab-set}
50+
51+
::::{tab-item} Output
52+
53+
:::{warning}
54+
This is a warning.
55+
:::
56+
57+
::::
58+
59+
::::{tab-item} Markdown
60+
61+
```markdown
62+
:::{warning}
63+
This is a warning.
64+
:::
65+
```
66+
67+
::::
68+
69+
:::::
70+
71+
### Tip
72+
73+
Advice to help users make better choices when using a feature.
74+
75+
You could permanently lose data or leak sensitive information.
76+
77+
:::::{tab-set}
78+
79+
::::{tab-item} Output
80+
81+
:::{tip}
82+
This is a tip.
83+
:::
84+
85+
::::
86+
87+
::::{tab-item} Markdown
88+
89+
```markdown
90+
:::{tip}
91+
This is a tip.
92+
:::
93+
```
94+
95+
::::
96+
97+
:::::
98+
99+
### Important
100+
101+
Ignoring this information could impact performance or the stability of your system.
102+
103+
:::::{tab-set}
104+
105+
::::{tab-item} Output
106+
107+
:::{important}
108+
This is an important notice.
109+
:::
110+
111+
::::
112+
113+
::::{tab-item} Markdown
114+
115+
```markdown
116+
:::{important}
117+
This is an important notice.
118+
:::
119+
```
120+
121+
::::
122+
123+
:::::
124+
125+
### Plain
126+
127+
A plain admonition is a callout with no further styling. Useful to create a callout that does not quite fit the mold of the stylized admonitions.
128+
129+
130+
131+
:::::{tab-set}
132+
133+
::::{tab-item} Output
134+
135+
:::{admonition} This is my callout
136+
It can *span* multiple lines and supports inline formatting.
137+
:::
138+
139+
::::
140+
141+
::::{tab-item} Markdown
142+
143+
```markdown
144+
:::{admonition} This is my callout
145+
It can *span* multiple lines and supports inline formatting.
146+
:::
147+
```
148+
149+
::::
150+
151+
:::::
152+
153+
## Applies to information
154+
155+
:::{include} _snippets/applies-to-admonitions.md
156+
:::

0 commit comments

Comments
 (0)