diff --git a/docs/syntax/index.md b/docs/syntax/index.md index 712a68519..21ee0d7cc 100644 --- a/docs/syntax/index.md +++ b/docs/syntax/index.md @@ -2,8 +2,9 @@ Elastic Docs V3 uses [Markdown](https://commonmark.org) as its main content authoring format. -:::{admonition} New to Markdown? -[Learn Markdown in just 10 minutes](https://commonmark.org/help/). +:::{admonition} New to Elastic Docs V3? +* Learn [Markdown](https://commonmark.org/help/) in 10 minutes +* Review the V3 [](quick-ref.md) ::: V3 fully supports [CommonMark](https://commonmark.org/), a strongly defined, standard-compliant Markdown specification. In many cases, plain Markdown syntax will be sufficient when authoring Elastic content. On top of this functionality, there are two main syntax extension points: diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md index ceaf69acc..152fe39c5 100644 --- a/docs/syntax/quick-ref.md +++ b/docs/syntax/quick-ref.md @@ -69,11 +69,14 @@ These examples show the syntax first, followed by the rendered admonition. :::: **DOs**
-✅ Use custom admonitions as needed +✅ **Do:** Use custom admonitions as needed **DON'Ts**
-❌ Stack admonitions
-❌ Overload a page with too many admonitions
+❌ **Don't:** Stack admonitions
+❌ **Don't:** Overload a page with too many admonitions + +[More details: Admonitions →](admonitions.md) +

--- @@ -97,11 +100,11 @@ A default anchor is automatically created for each [heading](#headings), in the ::: **DOs**
-✅ Create custom anchors for repeated structural headings like "Example request"
+✅ **Do:** Create custom anchors for repeated structural headings like "Example request"
**DON'Ts**
-❌ Include punctuation marks in custom anchors
-❌ Define custom anchors in text that is not a heading +❌ **Don't:** Include punctuation marks in custom anchors
+❌ **Don't:** Define custom anchors in text that is not a heading [More details: Links →](links.md#same-page-links-anchors)
@@ -142,14 +145,14 @@ The `applies_to` tags are scope signals for readers, not comprehensive metadata. % TODO restore details when guidance has settled **DOs**
-✅ Define a set of [page-level tags](applies.md#page-annotations) in a front matter block
-✅ Add section-level tags in an `{applies_to}` [directive](applies.md#sections) after a heading
-✅ Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` +✅ **Do:** Define a set of [page-level tags](applies.md#page-annotations) in a front matter block
+✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#sections) after a heading
+✅ **Do:** Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` **DON'Ts**
-❌ Include `applies_to` tags in admonitions
-❌ Add `applies_to` tags to general, broadly applicable content
-❌ Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features) +❌ **Don't:** Include `applies_to` tags in admonitions
+❌ **Don't:** Add `applies_to` tags to general, broadly applicable content
+❌ **Don't:** Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features)

@@ -177,12 +180,12 @@ elasticsearch.hosts: ["http://localhost:9200"] **DOs**
-✅ Include code blocks within lists or other block elements as needed
-✅ Add language identifiers like `yaml`, `json`, `bash` +✅ **Do:** Include code blocks within lists or other block elements as needed
+✅ **Do:** Add language identifiers like `yaml`, `json`, `bash` **DON'Ts**
-❌ Place code blocks in admonitions
-❌ Use inline code formatting (single backticks) for multi-line content
+❌ **Don't:** Place code blocks in admonitions
+❌ **Don't:** Use inline code formatting (single backticks) for multi-line content [More details: Code →](code.md)
@@ -250,12 +253,12 @@ Add comments with `//` or `#` to magically create callouts. ::: **DOs**
-✅ Keep callout text short and specific
-✅ Use only one type of callout per code block (don't mix [explicit](#explicit-callout) and [magic](#magic-callout))
-✅ Make sure there's a corresponding list item for each explicit callout marker in a code block +✅ **Do:** Keep callout text short and specific
+✅ **Do:** Use only one type of callout per code block (don't mix [explicit](#explicit-callout) and [magic](#magic-callout))
+✅ **Do:** Make sure there's a corresponding list item for each explicit callout marker in a code block **DON'Ts**
-❌ Overuse callouts -- they can impede readability
+❌ **Don't:** Overuse callouts — they can impede readability [More details: Code callouts→](code.md#code-callouts)
@@ -297,11 +300,11 @@ Regular text after multi-line comment ::: **DOs**
-✅ Add a space after `%` to start a single-line comment
+✅ **Do:** Add a space after the `%` in single-line comments **DON'Ts**
-❌ Use `#` or `//` for comments; they're reserved for [magic callouts](#magic-callout)
- +❌ **Don't:** Use `#` or `//` for comments (reserved for [magic callouts](#magic-callout)) +

--- @@ -325,11 +328,11 @@ Collapsible content :::: **DOs**
-✅ Use dropdowns for text, lists, images, code blocks, and tables
-✅ Add `:open:` to auto-expand a dropdown by default +✅ **Do:** Use dropdowns for text, lists, images, code blocks, and tables
+✅ **Do:** Add `:open:` to auto-expand a dropdown by default **DON'Ts**
-❌ Use dropdowns for very long paragraphs or entire sections
+❌ **Don't:** Use dropdowns for very long paragraphs or entire sections [More details: Dropdowns →](dropdowns.md)
@@ -359,13 +362,13 @@ Title of a page or a section. To create a heading, add number signs `#` at the b :::: **DOs**
-✅ Start every page with a Heading 1
-✅ Use only one Heading 1 per page
-✅ Define custom anchors for repeated headings
+✅ **Do:** Start every page with a Heading 1
+✅ **Do:** Use only one Heading 1 per page
+✅ **Do:** Define custom anchors for repeated headings **DON'Ts**
-❌ Use headings in tabs or dropdowns
-❌ Go deeper than Heading 4 +❌ **Don't:** Use headings in tabs or dropdowns
+❌ **Don't:** Go deeper than Heading 4 [More details: Headings →](headings.md)
@@ -387,14 +390,14 @@ Standard Markdown images: `[alt text]` in square brackets, followed by the image ::: **DOs**
-✅ Store images in a centralized directory
-✅ Follow v3 [best practices for screenshots](../versions/index.md#screenshots)
-✅ Specify `:screenshot:` in an [image directive](images.md#screenshots) to add a border
+✅ **Do:** Store images in a centralized directory
+✅ **Do:** Follow v3 [best practices for screenshots](../versions/index.md#screenshots)
+✅ **Do:** Specify `:screenshot:` in an [image directive](images.md#screenshots) to add a border **DON'Ts**
-❌ Use lots of UI screenshots that create a maintenance burden
-❌ Include confidential info or PII in an image
-❌ Add a drop shadow or torn edge effect +❌ **Don't:** Use lots of UI screenshots that create a maintenance burden
+❌ **Don't:** Include confidential info or PII in an image
+❌ **Don't:** Add a drop shadow or torn edge effect [More details: Images →](images.md)
@@ -410,14 +413,14 @@ Elastic Docs v3 supports standard Markdown inline formatting. `**strong**`    **bold**
\` `monospace` \`     `inline code` (single backticks)
`~~strikethrough~~`     ~~strikethrough~~
-`\* escaped`     \* escaped character
+`\* escaped`     \* escaped character **DOs**
-✅ Use `_emphasis_` to introduce a term
-✅ Use inline `code` in headings and other elements as needed +✅ **Do:** Use `_emphasis_` to introduce a term
+✅ **Do:** Use inline `code` in headings and other elements as needed **DON'Ts**
-❌ Overuse `**strong**` or `_emphasis_` -- aim for readability +❌ **Don't:** Overuse `**strong**` or `_emphasis_` — aim for readability

@@ -437,13 +440,13 @@ Standard Markdown links to doc pages, sections (anchors), or external content. P ::: **DOs**
-✅ Use inline formatting in link text: `[**bold link**](bold-page.md)`
-✅ Autogenerate link text from the page or section title: `[](use-title.md#section)`
-✅ Define a custom [anchor](#anchors) by adding `[anchor-text]` at the end of a heading line +✅ **Do:** Use inline formatting in link text: `[**bold link**](bold-page.md)`
+✅ **Do:** Autogenerate link text from the page or section title: `[](use-title.md#section)`
+✅ **Do:** Define a custom [anchor](#anchors) by adding `[anchor-text]` at the end of a heading line **DON'Ts**
-❌ Use unclear, inaccessible link text like "click here" or "this"
-❌ Include terminal punctuation in link text +❌ **Don't:** Use unclear, inaccessible link text like "click here" or "this"
+❌ **Don't:** Include terminal punctuation in link text [More details: Links →](links.md)
@@ -470,15 +473,15 @@ Standard Markdown ordered (numbered) and unordered (bulleted) lists. Indent with ::: **DOs**
-✅ Add code blocks, images, admonitions, and other content within a list item
-✅ Nest lists, mixing ordered and unordered as needed
-✅ Use parallel structure and phrasing in list items
-✅ Capitalize only the first word of list items (sentence case)
-✅ Use terminal punctuation consistently and only for complete sentences
+✅ **Do:** Add code blocks, images, admonitions, and other content within a list item
+✅ **Do:** Nest lists, mixing ordered and unordered as needed
+✅ **Do:** Use parallel structure and phrasing in list items
+✅ **Do:** Capitalize only the first word of list items (sentence case)
+✅ **Do:** Use terminal punctuation consistently and only for complete sentences **DON'Ts**
-❌ Use lists solely for layout purposes
-❌ Use lists for structured data or comparisons — use tables instead +❌ **Don't:** Use lists solely for layout purposes
+❌ **Don't:** Use lists for structured data or comparisons — use tables instead [More details: Lists →](lists.md)
@@ -516,14 +519,14 @@ Page title (Markdown H1): **DOs**
-✅ Use active phrasing and shorter forms
-✅ Make sure the navigation title clearly identifies the page topic
-✅ Omit product names that appear in the full H1 page title +✅ **Do:** Use active phrasing and shorter forms
+✅ **Do:** Make sure the navigation title clearly identifies the page topic
+✅ **Do:** Omit product names that appear in the full H1 page title **DON'Ts**
-❌ Duplicate the H1 page title
-❌ Use a long navigation title or lots of punctuation
-❌ Abbreviate with periods or ellipses +❌ **Don't:** Duplicate the H1 page title
+❌ **Don't:** Use a long navigation title or lots of punctuation
+❌ **Don't:** Abbreviate with periods or ellipses [More details: Title →](./titles.md)
@@ -571,13 +574,13 @@ Elastic Cloud Hosted supports most standard Kibana settings. ::: **DOs**
-✅ Check the global `docset.yml` file for existing product and feature name subs
-✅ Use substitutions in code blocks by setting `subs=true`
-✅ Define new page-specific substitutions as needed +✅ **Do:** Check the global `docset.yml` file for existing product and feature name subs
+✅ **Do:** Use substitutions in code blocks by setting `subs=true`
+✅ **Do:** Define new page-specific substitutions as needed **DON'Ts**
-❌ Override a `docset.yml` sub by defining a page-level sub with the same key (causes build errors)
-❌ Use substitutions for common words that don't need to be standardized +❌ **Don't:** Override a `docset.yml` sub by defining a page-level sub with the same key (causes build errors)
+❌ **Don't:** Use substitutions for common words that don't need to be standardized [More details: Substitutions →](./substitutions.md)
@@ -620,16 +623,16 @@ Tab 2 content ::::: **DOs**
-✅ Use clear, descriptive tab labels
-✅ Make sure all tabs have the same type of content and similar goals
-✅ Keep tab content scannable and self-contained (don't make the user switch tabs to follow steps or compare content)
-✅ Include other block elements in tabs, like [admonitions](#admonitions) +✅ **Do:** Use clear, descriptive tab labels
+✅ **Do:** Make sure all tabs have the same type of content and similar goals
+✅ **Do:** Keep tab content scannable and self-contained (don't make users switch tabs to follow steps or compare content)
+✅ **Do:** Include other block elements in tabs, like [admonitions](#admonitions) **DON'Ts**
-❌ Nest tabs
-❌ Split step-by-step procedures across tabs
-❌ Use more than 6 tabs (use as few as possible)
-❌ Use tabs in [dropdowns](#dropdowns) +❌ **Don't:** Nest tabs
+❌ **Don't:** Split step-by-step procedures across tabs
+❌ **Don't:** Use more than 6 tabs (use as few as possible)
+❌ **Don't:** Use tabs in [dropdowns](#dropdowns) [More details: Tabs →](tabs.md) @@ -659,13 +662,13 @@ Standard table layout for structured data. Automatically scrolls horizontally if ::: **DOs**
-✅ Use leading and trailing pipes for clarity
-✅ Add spaces for readability (they're trimmed)
-✅ Keep cell content scannable and parallel
-✅ Use standard Markdown text alignment when necessary (`:-- --: :--:`)
+✅ **Do:** Use leading and trailing pipes for clarity
+✅ **Do:** Add spaces for readability (they're trimmed)
+✅ **Do:** Keep cell content scannable and parallel
+✅ **Do:** Use standard Markdown text alignment when necessary (`:-- --: :--:`) **DON'Ts**
-❌ Insert block elements or multiple paragraphs in a table cell
-❌ Use a table solely for position or spacing purposes
+❌ **Don't:** Insert block elements or multiple paragraphs in a table cell
+❌ **Don't:** Use a table solely for position or spacing purposes [More details: Tables →](tables.md)