AWS eks documentation change
Summary
Updated AsciiDoc syntax guide with restructured content, added examples for headings, text formatting, lists, code blocks, tables, callouts, includes, attributes, and procedures. Enhanced documentation standards and removed Markdown references.
Security assessment
The changes focus on improving documentation structure, syntax examples, and contributor guidelines. No security vulnerabilities, configurations, or security-specific features are mentioned. Updates relate to formatting standards and content organization rather than security controls.
Diff
diff --git a/eks/latest/userguide/asciidoc-syntax.md b/eks/latest/userguide/asciidoc-syntax.md index 14a0c2110..a3daf553e 100644 --- a//eks/latest/userguide/asciidoc-syntax.md +++ b//eks/latest/userguide/asciidoc-syntax.md @@ -5 +5 @@ -Basic formattingHeadersListsLinksImagesCode BlocksTablesAdmonitionsIncludes +New pageHeadingsText formattingListsLinksCode examplesImagesTablesCalloutsIncluding other filesAttributesProcedures @@ -11 +11 @@ To contribute to this user guide, choose the **Edit this page on GitHub** link t -# AsciiDoc Syntax Reference +# AsciiDoc syntax reference @@ -13 +13 @@ To contribute to this user guide, choose the **Edit this page on GitHub** link t -This page is a quick overview of AsciiDoc syntax. +AsciiDoc is the preferred markup language for AWS documentation. While the tooling has partial support for Markdown syntax (such as headings and lists), we recommend using AsciiDoc syntax for all content to ensure consistency and proper rendering. @@ -15 +15 @@ This page is a quick overview of AsciiDoc syntax. -We suggest using AsciiDoc syntax. The AsciiDoc tooling has partial support for Markdown syntax, including headings and lists. +This guide covers common syntax elements you’ll need when contributing to Amazon EKS documentation. For more advanced syntax and detailed information, refer to the [AsciiDoc documentation](https://docs.asciidoctor.org/asciidoc/latest/). @@ -17 +17 @@ We suggest using AsciiDoc syntax. The AsciiDoc tooling has partial support for M -For advanced syntax, review the [AsciiDoc Website](https://docs.asciidoctor.org/asciidoc/latest/). +## New page @@ -19 +19 @@ For advanced syntax, review the [AsciiDoc Website](https://docs.asciidoctor.org/ -It’s important to get the link syntax right for the AWS docs. Review how to [Insert a link](./insert-link.html). You cannot use Markdown syntax for links. +Every new AsciiDoc document should begin with the structure defined in [Create a new page](./create-page.html). @@ -21 +21 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I -## Basic formatting +## Headings @@ -22,0 +23 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I +Use headings to organize your content hierarchically: @@ -24,3 +24,0 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I - *bold text* - _italic text_ - `monospace text` @@ -28 +26,6 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I -## Headers + = Page/topic title (level 1) + == Section title (level 2) + === Level 3 heading + ==== Level 4 heading + ===== Level 5 heading + ====== Level 6 heading @@ -29,0 +33 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I +Note: Always use sentence case for headings in AWS documentation. @@ -31,6 +35,8 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I - = Document Title (Header 1) - == Header 2 - === Header 3 - ==== Header 4 - ===== Header 5 - ====== Header 6 +## Text formatting + +Format text to emphasize important information: + + + Use *bold text* for UI labels. + Use _italic text_ for introducing terms or light emphasis. + Use `monospace text` for code, file names, and commands. @@ -40 +46,3 @@ It’s important to get the link syntax right for the AWS docs. Review how to [I -Unordered Lists: +### Unordered lists + +Create bulleted lists for items without a specific sequence: @@ -43,5 +51,5 @@ Unordered Lists: - - Item 1 - - Item 2 - -- Subitem 2.1 - -- Subitem 2.2 - - Item 3 + * First item + * Second item + ** Nested item + ** Another nested item + * Third item @@ -49 +57 @@ Unordered Lists: -Ordered Lists: +### Ordered lists @@ -50,0 +59 @@ Ordered Lists: +Create numbered lists for sequential steps or prioritized items: @@ -52,5 +61,6 @@ Ordered Lists: - . First item - . Second item - .. Subitem 2.1 - .. Subitem 2.2 - . Third item + + . First step + . Second step + .. Substep 1 + .. Substep 2 + . Third step @@ -59,0 +70 @@ Ordered Lists: +See [Insert a link](./insert-link.html) for details on how to properly format links. Markdown-style links are not supported. @@ -61,3 +72 @@ Ordered Lists: - External link: https://example.com[Link text] - Internal link: <<page-id>> - Internal link: <<page-id,Link text>> +## Code examples @@ -65 +74,3 @@ Ordered Lists: -## Images +### Inline code + +Use backticks for inline code: @@ -68 +79 @@ Ordered Lists: - image::image-file.jpg[Alt text] + Use the `kubectl get pods` command to list all pods. @@ -70 +81,3 @@ Ordered Lists: -## Code Blocks +### Code blocks + +Create code blocks with syntax highlighting: @@ -78,0 +92,7 @@ Ordered Lists: +## Images + +Insert images with alt text for accessibility: + + + image::images/image-file.png[Alt text description] + @@ -81 +101 @@ Ordered Lists: -[Learn how to build a basic table.](https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/) +Create tables to organize information: @@ -86,3 +106,2 @@ Ordered Lists: - |Cell in column 1, header row - |Cell in column 2, header row - + |Header 1 + |Header 2 @@ -90,5 +109,2 @@ Ordered Lists: - |Cell in column 1, body row 1 - |Cell in column 2, body row 1 - - |Cell in column 1, body row 2 - |Cell in column 2, body row 2 + |Cell 1,1 + |Cell 1,2 @@ -95,0 +112,2 @@ Ordered Lists: + |Cell 2,1 + |Cell 2,2 @@ -98 +116 @@ Ordered Lists: -## Admonitions +For more complex tables, see the [AsciiDoc table documentation](https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/). @@ -99,0 +118 @@ Ordered Lists: +## Callouts @@ -101 +120 @@ Ordered Lists: - NOTE: This is a note admonition. +Use callouts to highlight important information and admonitions: @@ -103 +121,0 @@ Ordered Lists: - WARNING: This is a warning admonition. @@ -105 +123 @@ Ordered Lists: - TIP: This is a tip admonition. + NOTE: This is a note callout for general information. @@ -107 +125 @@ Ordered Lists: - IMPORTANT: This is an important admonition. + TIP: This is a tip callout for helpful advice. @@ -109 +127 @@ Ordered Lists: - CAUTION: This is a caution admonition. + IMPORTANT: This is an important callout for critical information. @@ -115 +133,3 @@ Preview: -This is a note admonition. +This is a note callout. + +## Including other files @@ -117 +137 @@ This is a note admonition. -## Includes +Include content from other files: @@ -121,0 +142,22 @@ This is a note admonition. +## Attributes + +Use predefined attributes to maintain consistency. In particular, you MUST use an attribute for ` AWS `. + + + {aws} provides Amazon EKS as a managed Kubernetes service. + +For a list of attributes, look in the `../attributes.txt` file. + +## Procedures + +Format step-by-step procedures: + + + To create an Amaozon EKS cluster. do the following steps. + + . Sign in to the {aws} Management Console. + . Open the Amazon EKS console. + . Choose *Create cluster*. + + ... +