docs-syntax-help

Name: docs-syntax-help
Author: elastic

71stars10forks

How to install docs-syntax-help?

elastic/elastic-docs-skills/docs-syntax-help

$npx -y skills add elastic/elastic-docs-skills --skill docs-syntax-help

Installs into the current project.

Summary

Provide Elastic Docs syntax guidance, troubleshoot markup issues, and help write directives correctly. Use when writing or editing documentation that uses MyST Markdown with Elastic extensions, or when troubleshooting build errors related to syntax.

Files · 1

View on GitHub

SKILL.md

1	<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
2	or more contributor license agreements. See the NOTICE file distributed with
3	this work for additional information regarding copyright
4	ownership. Elasticsearch B.V. licenses this file to you under
5	the Apache License, Version 2.0 (the "License"); you may
6	not use this file except in compliance with the License.
7	You may obtain a copy of the License at
8
9	http://www.apache.org/licenses/LICENSE-2.0
10
11	Unless required by applicable law or agreed to in writing,
12	software distributed under the License is distributed on an
13	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14	KIND, either express or implied. See the License for the
15	specific language governing permissions and limitations
16	under the License. -->
17
18	You are an Elastic Docs syntax expert. Your job is to help users write correct MyST Markdown with Elastic-specific extensions, troubleshoot syntax errors, and fix malformed directives.
19
20	## Directive syntax fundamentals
21
22	Directives use colon-fenced blocks with the directive name in curly braces:
23
24	```
25	:::{directive-name} [argument]
26	:option: value
27	Content here
28	:::
29	```
30
31	- Opening: Three or more colons, directive name in `{}`
32	- Argument: Optional, on the same line after the name
33	- Options: One per line, colon-prefixed (`:option: value`)
34	- Content: Markdown-processed body
35	- Closing: Same number of colons as opening
36
37	### Nesting directives
38
39	Outer directives need MORE colons than inner ones. Add one colon per nesting level:
40
41	```
42	::::{tab-set}
43	:::{tab-item} First
44	Content
45	:::
46	:::{tab-item} Second
47	Content
48	:::
49	::::
50	```
51
52	Three levels deep:
53
54	```
55	::::::{stepper}
56	:::::{step} Title
57	::::{tab-set}
58	:::{tab-item} Option A
59	Content
60	:::
61	::::
62	:::::
63	::::::
64	```
65
66	### Literal blocks inside directives
67
68	Code blocks use backtick fences (not colons) to prevent Markdown processing:
69
70	````
71	:::{note}
72	```yaml
73	key: value
74	```
75	:::
76	````
77
78	## Admonitions
79
80	Four standard types plus custom:
81
82	```
83	:::{note}
84	Supplemental information. No serious repercussions if ignored.
85	:::
86
87	:::{tip}
88	Advice to help users work more efficiently.
89	:::
90
91	:::{important}
92	Ignoring this could impact performance or stability.
93	:::
94
95	:::{warning}
96	Users could permanently lose data or leak sensitive information.
97	:::
98
99	:::{admonition} Custom title
100	Plain callout with a custom title and no severity styling.
101	:::
102	```
103
104	Rules: Do not stack admonitions. Do not place code blocks inside admonitions (use dropdowns or tabs instead if code is long).
105
106	## Headings
107
108	```
109	# Page title (h1 — exactly one per page, must be first)
110	## Section (h2)
111	### Subsection (h3)
112	#### Sub-subsection (h4)
113	```
114
115	Custom anchors: `#### My heading [custom-anchor-id]`
116
117	Default anchors auto-generate as lowercase, hyphenated, alphanumeric (diacritics removed).
118
119	## Links
120
121	Internal (relative or absolute with `.md` extension):
122	```
123	[Link text](../path/to/page.md)
124	[Link text](/absolute/path/to/page.md#anchor)
125	```
126
127	Same-page anchor: `[Jump](#section-anchor)`
128
129	Cross-repository: `[Text](kibana://path/to/page.md)` — link text is mandatory; omitting it causes the link to fail.
130
131	External: `[Text](https://example.com)` — bare `https://` URLs (not `http://`) are automatically converted to clickable links that open in a new tab. Autolinks are not rendered inside code blocks or inline code. Bare URL autolinks pointing to `elastic.co/docs` trigger a build hint to use a cross-repository or relative link instead.
132
133	Auto-generated text (uses target page title): `[](page.md)` or `[](page.md#section)`
134
135	Reference-style:
136	```
137	[link text][ref-id]
138
139	[ref-id]: https://example.com
140	```
141
142	## Code blocks
143
144	````
145	```yaml
146	key: value
147	```
148	````
149
150	### Explicit callouts
151
152	Add `<N>` markers at line ends, followed by a matching numbered list:
153
154	````
155	```yaml
156	host: "0.0.0.0" <1>
157	port: 9200 <2>
158	```
159
160	1. Bind address
161	2. Port number
162	````
163
164	The list item count must match the callout count exactly.
165
166	### Automatic callouts
167
168	Comments on code lines become callouts automatically:
169
170	````
171	```csharp
172	var key = new ApiKey("<KEY>"); // Set up the API key
173	```
174	````
175
176	Disable callout processing: ````callouts=false`
177
178	Rule: Do not mix explicit and automatic callouts in the same code block — use only one type per block.
179
180	### Console code blocks
181
182	Use `console` as the language. First line renders as a dev console command; rest as JSON.
183
184	### Substitutions in code
185
186	Enable with `subs=true`:
187
188	````
189	```bash subs=tr

People who liked this also viewed

6 picks

Type

docs-syntax-help

71stars10forks

View on GitHub

How to install docs-syntax-help?

elastic/elastic-docs-skills/docs-syntax-help

$npx -y skills add elastic/elastic-docs-skills --skill docs-syntax-help

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
2	or more contributor license agreements. See the NOTICE file distributed with
3	this work for additional information regarding copyright
4	ownership. Elasticsearch B.V. licenses this file to you under
5	the Apache License, Version 2.0 (the "License"); you may
6	not use this file except in compliance with the License.
7	You may obtain a copy of the License at
8
9	http://www.apache.org/licenses/LICENSE-2.0
10
11	Unless required by applicable law or agreed to in writing,
12	software distributed under the License is distributed on an
13	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14	KIND, either express or implied. See the License for the
15	specific language governing permissions and limitations
16	under the License. -->
17
18	You are an Elastic Docs syntax expert. Your job is to help users write correct MyST Markdown with Elastic-specific extensions, troubleshoot syntax errors, and fix malformed directives.
19
20	## Directive syntax fundamentals
21
22	Directives use colon-fenced blocks with the directive name in curly braces:
23
24	```
25	:::{directive-name} [argument]
26	:option: value
27	Content here
28	:::
29	```
30
31	- Opening: Three or more colons, directive name in `{}`
32	- Argument: Optional, on the same line after the name
33	- Options: One per line, colon-prefixed (`:option: value`)
34	- Content: Markdown-processed body
35	- Closing: Same number of colons as opening
36
37	### Nesting directives
38
39	Outer directives need MORE colons than inner ones. Add one colon per nesting level:
40
41	```
42	::::{tab-set}
43	:::{tab-item} First
44	Content
45	:::
46	:::{tab-item} Second
47	Content
48	:::
49	::::
50	```
51
52	Three levels deep:
53
54	```
55	::::::{stepper}
56	:::::{step} Title
57	::::{tab-set}
58	:::{tab-item} Option A
59	Content
60	:::
61	::::
62	:::::
63	::::::
64	```
65
66	### Literal blocks inside directives
67
68	Code blocks use backtick fences (not colons) to prevent Markdown processing:
69
70	````
71	:::{note}
72	```yaml
73	key: value
74	```
75	:::
76	````
77
78	## Admonitions
79
80	Four standard types plus custom:
81
82	```
83	:::{note}
84	Supplemental information. No serious repercussions if ignored.
85	:::
86
87	:::{tip}
88	Advice to help users work more efficiently.
89	:::
90
91	:::{important}
92	Ignoring this could impact performance or stability.
93	:::
94
95	:::{warning}
96	Users could permanently lose data or leak sensitive information.
97	:::
98
99	:::{admonition} Custom title
100	Plain callout with a custom title and no severity styling.
101	:::
102	```
103
104	Rules: Do not stack admonitions. Do not place code blocks inside admonitions (use dropdowns or tabs instead if code is long).
105
106	## Headings
107
108	```
109	# Page title (h1 — exactly one per page, must be first)
110	## Section (h2)
111	### Subsection (h3)
112	#### Sub-subsection (h4)
113	```
114
115	Custom anchors: `#### My heading [custom-anchor-id]`
116
117	Default anchors auto-generate as lowercase, hyphenated, alphanumeric (diacritics removed).
118
119	## Links
120
121	Internal (relative or absolute with `.md` extension):
122	```
123	[Link text](../path/to/page.md)
124	[Link text](/absolute/path/to/page.md#anchor)
125	```
126
127	Same-page anchor: `[Jump](#section-anchor)`
128
129	Cross-repository: `[Text](kibana://path/to/page.md)` — link text is mandatory; omitting it causes the link to fail.
130
131	External: `[Text](https://example.com)` — bare `https://` URLs (not `http://`) are automatically converted to clickable links that open in a new tab. Autolinks are not rendered inside code blocks or inline code. Bare URL autolinks pointing to `elastic.co/docs` trigger a build hint to use a cross-repository or relative link instead.
132
133	Auto-generated text (uses target page title): `[](page.md)` or `[](page.md#section)`
134
135	Reference-style:
136	```
137	[link text][ref-id]
138
139	[ref-id]: https://example.com
140	```
141
142	## Code blocks
143
144	````
145	```yaml
146	key: value
147	```
148	````
149
150	### Explicit callouts
151
152	Add `<N>` markers at line ends, followed by a matching numbered list:
153
154	````
155	```yaml
156	host: "0.0.0.0" <1>
157	port: 9200 <2>
158	```
159
160	1. Bind address
161	2. Port number
162	````
163
164	The list item count must match the callout count exactly.
165
166	### Automatic callouts
167
168	Comments on code lines become callouts automatically:
169
170	````
171	```csharp
172	var key = new ApiKey("<KEY>"); // Set up the API key
173	```
174	````
175
176	Disable callout processing: ````callouts=false`
177
178	Rule: Do not mix explicit and automatic callouts in the same code block — use only one type per block.
179
180	### Console code blocks
181
182	Use `console` as the language. First line renders as a dev console command; rest as JSON.
183
184	### Substitutions in code
185
186	Enable with `subs=true`:
187
188	````
189	```bash subs=tr

People who liked this also viewed

6 picks

Type