Merge pull request #22 from aws-samples/markdown-formatting

unordered list bullets and trailing whitespace

Author: mwunderl

instra/tutorial-gen/0-general-instructions.md

@@ -13,3 +13,6 @@ When creating tutorials for specific AWS services:
 1. CRITICAL FOR VPC CREATION:
    - Use the architecture defined in vpc-example.md as reference
    - This step is mandatory before creating any VPC resources
+2. CRITICAL FOR MARKDOWN FORMATTING:
+   - Follow the markdown-formatting-guide.md for consistent formatting
+   - Always use hyphens (-) for lists, never asterisks (*) or bullet characters (•)

instra/tutorial-gen/3a-draft-tutorial.md

@@ -1,36 +1,41 @@
-# draft a tutorial
-
-Use the example commands and output in cli-workflow.md to generate a tutorial, with a section for each group of related commands, and sections on prerequisites and next steps. Include guidance before and after every code block, even if it's just one sentence. reference the content in golden-tutorial.md as an example of a good tutorial. If content in the prerequisites section of the golden tutorial applies to this tutorial, reuse it. Name the output file 3-tutorial-draft.md.
-
-## links
-
-The tutorial may be published in the service guide, so don't include any general links to the guide or documentation landing page. In the next steps section, link to a topic in the service guide for each feature or use case listed. The prerequisites section can also have links, but avoid adding links to the core sections of the tutorial where readers are following instructions. Links in these sections can pull the reader away from the tutorial unnecessarily. 
-
-## formatting
-
-Only use two levels of headers. H1 for the topic title, and H2 for the sections. To add a title to a code block or procedure, just use bold text.
-
-Use sentence case for all headers and titles.
-Use present tense and active voice as much as possible.
-
-Don't add linebreaks in the middle of a paragraph. Keep all of the text in the paragraph on one line. Ensure that there is an empty line between all headers, paragraphs, example titles, and code blocks.
-
-For any relative path links, replace the './' with the full path that it represents.
-
-## portability
-
-Omit the --region option in example commands, unless it is required because by the specific use case or the service API. For example, if a command requires you to specify an availability zone, you need to ensure that you are calling the service in the same AWS Region as the availability zone. Otherwise, assume that the reader wants to create resources in the Region that they configured when they set up the AWS CLI, or write a script that they can run in any Region.
-
-## naming rules
-
-**account ids** - Replace 12 digit AWS account numbers with 123456789012. For examples with two account numbers, use 234567890123 for the second number. 
-
-**GUIDs** - Obfuscate GUIDs by making the second character sequence in the guid "xmpl". 
-
-**resource IDs** - For hex sequences, replace characters in the example with "abcd1234". For other numeric IDs, renumber starting with 1234. For alphanumric ID strings, replace characters 5-8 with "xmpl". 
-
-**timestamps** - Replace timestamps with a value representing January 13th of the current year. 
-
-**IP addresses** - Replace public IP addresses with fictitious addresses such as 203.0.113.75 or another address in the 203.0.113
-
+# draft a tutorial
+
+Use the example commands and output in cli-workflow.md to generate a tutorial, with a section for each group of related commands, and sections on prerequisites and next steps. Include guidance before and after every code block, even if it's just one sentence. reference the content in golden-tutorial.md as an example of a good tutorial. If content in the prerequisites section of the golden tutorial applies to this tutorial, reuse it. Name the output file 3-tutorial-draft.md.
+
+## links
+
+The tutorial may be published in the service guide, so don't include any general links to the guide or documentation landing page. In the next steps section, link to a topic in the service guide for each feature or use case listed. The prerequisites section can also have links, but avoid adding links to the core sections of the tutorial where readers are following instructions. Links in these sections can pull the reader away from the tutorial unnecessarily. 
+
+## formatting
+
+Only use two levels of headers. H1 for the topic title, and H2 for the sections. To add a title to a code block or procedure, just use bold text.
+
+Use sentence case for all headers and titles.
+Use present tense and active voice as much as possible.
+
+Don't add linebreaks in the middle of a paragraph. Keep all of the text in the paragraph on one line. Ensure that there is an empty line between all headers, paragraphs, example titles, and code blocks.
+
+**List formatting:**
+- Always use hyphens (-) for unordered lists, never asterisks (*) or bullet characters (•)
+- Maintain consistent indentation for nested lists
+- Example: `- First item` not `* First item` or `• First item`
+
+For any relative path links, replace the './' with the full path that it represents.
+
+## portability
+
+Omit the --region option in example commands, unless it is required because by the specific use case or the service API. For example, if a command requires you to specify an availability zone, you need to ensure that you are calling the service in the same AWS Region as the availability zone. Otherwise, assume that the reader wants to create resources in the Region that they configured when they set up the AWS CLI, or write a script that they can run in any Region.
+
+## naming rules
+
+**account ids** - Replace 12 digit AWS account numbers with 123456789012. For examples with two account numbers, use 234567890123 for the second number. 
+
+**GUIDs** - Obfuscate GUIDs by making the second character sequence in the guid "xmpl". 
+
+**resource IDs** - For hex sequences, replace characters in the example with "abcd1234". For other numeric IDs, renumber starting with 1234. For alphanumric ID strings, replace characters 5-8 with "xmpl". 
+
+**timestamps** - Replace timestamps with a value representing January 13th of the current year. 
+
+**IP addresses** - Replace public IP addresses with fictitious addresses such as 203.0.113.75 or another address in the 203.0.113
+
 **bucket names** - For S3 buckets, the name in the tutorial must start with "amzn-s3-demo". The script can't use this name because it's reserved for documentation. Leave the script as is but replace the prefix used by the script with "amzn-s3-demo" in the tutorial.

instra/tutorial-gen/3b-validate-tutorial.md

@@ -5,6 +5,11 @@ Validating the content of the AWS CLI tutorial and surface issues about the gene
 
 Review the tutorial markdown for proper formatting:
 
+**List formatting:**
+- Verify all unordered lists use hyphens (-) consistently, never asterisks (*) or bullet characters (•)
+- Check for consistent indentation in nested lists
+- Flag any mixed list marker usage within the same document
+
 **Backticks usage:**
 - Use backticks for all inline code, commands, file paths, resource IDs, status values, and technical terms
 - Examples: `aws s3 ls`, `my-bucket-name`, `ACTIVE`, `~/path/to/file`, `us-east-1`

instra/tutorial-gen/golden-tutorial.md

@@ -4,14 +4,14 @@ This tutorial guides you through common Amazon Lightsail operations using the AW
 
 ## Topics
 
-* [Prerequisites](#getstarted-awscli-prerequisites)
-* [Generate SSH key pairs](#getstarted-awscli-generate-ssh-key-pairs)
-* [Create and manage instances](#getstarted-awscli-create-and-manage-instances)
-* [Connect to your instance](#getstarted-awscli-connect-to-your-instance)
-* [Add storage to your instance](#getstarted-awscli-add-storage-to-your-instance)
-* [Create and use snapshots](#getstarted-awscli-create-and-use-snapshots)
-* [Clean up resources](#getstarted-awscli-clean-up-resources)
-* [Next steps](#getstarted-awscli-next-steps)
+- [Prerequisites](#getstarted-awscli-prerequisites)
+- [Generate SSH key pairs](#getstarted-awscli-generate-ssh-key-pairs)
+- [Create and manage instances](#getstarted-awscli-create-and-manage-instances)
+- [Connect to your instance](#getstarted-awscli-connect-to-your-instance)
+- [Add storage to your instance](#getstarted-awscli-add-storage-to-your-instance)
+- [Create and use snapshots](#getstarted-awscli-create-and-use-snapshots)
+- [Clean up resources](#getstarted-awscli-clean-up-resources)
+- [Next steps](#getstarted-awscli-next-steps)
 
 ## Prerequisites
 

instra/tutorial-gen/markdown-formatting-guide.md

@@ -0,0 +1,32 @@
+# Markdown Formatting Guide
+
+This guide ensures consistent markdown formatting across all tutorials to prevent rendering issues.
+
+## List Formatting Rules
+
+**REQUIRED:** Always use hyphens (-) for unordered lists
+- ✅ Correct: `- First item`
+- ❌ Incorrect: `* First item`
+- ❌ Incorrect: `• First item`
+
+**Consistency:** Use the same list marker throughout the entire document
+- All lists in a single file must use hyphens (-)
+- Never mix asterisks (*) and hyphens (-) in the same document
+- Never use bullet characters (•) which are not standard markdown
+
+## Whitespace Rules
+
+**Trailing whitespace:** Remove all trailing whitespace from lines
+- Use `sed -i 's/[[:space:]]*$//' filename.md` to clean up
+
+**Line endings:** Use Unix line endings (LF) not Windows (CRLF)
+- Use `sed -i 's/\r$//' filename.md` to convert if needed
+
+## Validation Checklist
+
+Before submitting any tutorial, verify:
+- [ ] All lists use hyphens (-) consistently
+- [ ] No bullet characters (•) are present
+- [ ] No trailing whitespace on any lines
+- [ ] Unix line endings are used
+- [ ] Consistent indentation for nested lists

tuts/001-lightsail-gs/README.md

@@ -8,8 +8,8 @@ You can either run the automated script `lightsail-gs.sh` to execute all operati
 
 The script creates the following AWS resources in order:
 
-• Lightsail instance (nano_3_0 bundle with Amazon Linux 2023)
-• Lightsail disk (8 GB block storage disk)
-• Lightsail instance snapshot (backup of the instance)
+- Lightsail instance (nano_3_0 bundle with Amazon Linux 2023)
+- Lightsail disk (8 GB block storage disk)
+- Lightsail instance snapshot (backup of the instance)
 
 The script prompts you to clean up resources when you run it, including if there's an error part way through. If you need to clean up resources later, you can use the script log as a reference point for which resources were created.

tuts/002-vpc-gs/README.md

@@ -8,21 +8,21 @@ You can either run the automated script `vpc-gs.sh` to execute all operations au
 
 The script creates the following AWS resources in order:
 
-• EC2 VPC (10.0.0.0/16 CIDR block with DNS support and hostnames enabled)
-• EC2 subnet (public subnet in AZ1 - 10.0.0.0/24)
-• EC2 subnet (public subnet in AZ2 - 10.0.1.0/24)
-• EC2 subnet (private subnet in AZ1 - 10.0.2.0/24)
-• EC2 subnet (private subnet in AZ2 - 10.0.3.0/24)
-• EC2 internet gateway (for public internet access)
-• EC2 route table (public route table with internet gateway route)
-• EC2 route table association (public subnet AZ1 to public route table)
-• EC2 route table association (public subnet AZ2 to public route table)
-• EC2 route table (private route table)
-• EC2 route table association (private subnet AZ1 to private route table)
-• EC2 route table association (private subnet AZ2 to private route table)
-• EC2 elastic IP (for NAT gateway)
-• EC2 NAT gateway (in public subnet AZ1 for private subnet internet access)
-• EC2 security group (web server security group allowing HTTP/HTTPS)
-• EC2 security group (database security group allowing MySQL from web servers)
+- EC2 VPC (10.0.0.0/16 CIDR block with DNS support and hostnames enabled)
+- EC2 subnet (public subnet in AZ1 - 10.0.0.0/24)
+- EC2 subnet (public subnet in AZ2 - 10.0.1.0/24)
+- EC2 subnet (private subnet in AZ1 - 10.0.2.0/24)
+- EC2 subnet (private subnet in AZ2 - 10.0.3.0/24)
+- EC2 internet gateway (for public internet access)
+- EC2 route table (public route table with internet gateway route)
+- EC2 route table association (public subnet AZ1 to public route table)
+- EC2 route table association (public subnet AZ2 to public route table)
+- EC2 route table (private route table)
+- EC2 route table association (private subnet AZ1 to private route table)
+- EC2 route table association (private subnet AZ2 to private route table)
+- EC2 elastic IP (for NAT gateway)
+- EC2 NAT gateway (in public subnet AZ1 for private subnet internet access)
+- EC2 security group (web server security group allowing HTTP/HTTPS)
+- EC2 security group (database security group allowing MySQL from web servers)
 
 The script prompts you to clean up resources when you run it, including if there's an error part way through. If you need to clean up resources later, you can use the script log as a reference point for which resources were created.

tuts/003-s3-gettingstarted/README.md

@@ -8,14 +8,14 @@ You can either run the automated script `s3-gettingstarted.sh` to execute all op
 
 The script creates the following AWS resources in order:
 
-• S3 bucket (primary bucket for tutorial)
-• S3 bucket (secondary bucket for cross-region replication)
-• S3 public access block configuration
-• S3 bucket versioning configuration
-• S3 bucket encryption configuration
-• S3 object (sample text file)
-• S3 object (sample image file)
-• S3 object (sample document file)
-• S3 bucket tagging configuration
+- S3 bucket (primary bucket for tutorial)
+- S3 bucket (secondary bucket for cross-region replication)
+- S3 public access block configuration
+- S3 bucket versioning configuration
+- S3 bucket encryption configuration
+- S3 object (sample text file)
+- S3 object (sample image file)
+- S3 object (sample document file)
+- S3 bucket tagging configuration
 
 The script prompts you to clean up resources when you run it, including if there's an error part way through. If you need to clean up resources later, you can use the script log as a reference point for which resources were created.

tuts/004-cloudmap-custom-attributes/README.md

@@ -8,22 +8,22 @@ You can either run the automated script `cloudmap-custom-attributes.sh` to execu
 
 The script creates the following AWS resources in order:
 
-• Service Discovery http namespace
-• Service Discovery http namespace (b)
-• DynamoDB table
-• Service Discovery service
-• Service Discovery instance
-• Service Discovery instance (b)
-• IAM role
-• IAM policy
-• IAM role policy
-• IAM role policy (b)
-• Service Discovery service (b)
-• Lambda function
-• Service Discovery instance (c)
-• Service Discovery instance (d)
-• Lambda function (b)
-• Service Discovery instance (e)
-• Service Discovery instance (f)
+- Service Discovery http namespace
+- Service Discovery http namespace (b)
+- DynamoDB table
+- Service Discovery service
+- Service Discovery instance
+- Service Discovery instance (b)
+- IAM role
+- IAM policy
+- IAM role policy
+- IAM role policy (b)
+- Service Discovery service (b)
+- Lambda function
+- Service Discovery instance (c)
+- Service Discovery instance (d)
+- Lambda function (b)
+- Service Discovery instance (e)
+- Service Discovery instance (f)
 
 The script prompts you to clean up resources when you run it, including if there's an error part way through. If you need to clean up resources later, you can use the script log as a reference point for which resources were created.