From 01297330798194435c10ece87ec96ac04f863cc1 Mon Sep 17 00:00:00 2001 From: Karuna Tata <74637789+starlightknown@users.noreply.github.com> Date: Mon, 20 Feb 2023 13:51:28 +0530 Subject: [PATCH 01/15] Create formatting.md --- docs/community/styleguide/formatting.md | 27 +++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/community/styleguide/formatting.md diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md new file mode 100644 index 000000000000..103e028e40a9 --- /dev/null +++ b/docs/community/styleguide/formatting.md @@ -0,0 +1,27 @@ +--- +title: Formatting style guide +description: This style guide explains about using correct formats when writing documenation. +weight: +--- +## Documentation formatting + +### Notes and warning blocks + +Notes and warning blocks are used to draw attention to important information. Use the following markdown features when necessary: + +- Use a clear and concise heading to introduce the note or warning. +- Use short paragraphs or bullet points to convey the information. +- Keep the language simple and direct. +- Use an `>` in markdown to indicate the nature of the note or warning. +- Use the following Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: + * Surround the text with an opening and closing tag. + * Use the following syntax to apply a style: +` +No need to add a prefix (Remember); the tag automatically provides one +` + +The output: + + +No need to add a prefix (Remember); the tag automatically provides one + From 5e528a3f906de3ac16475d70eb72bdb470fe3228 Mon Sep 17 00:00:00 2001 From: Karuna Tata <74637789+starlightknown@users.noreply.github.com> Date: Mon, 20 Feb 2023 14:33:14 +0530 Subject: [PATCH 02/15] add: code blocks --- docs/community/styleguide/formatting.md | 50 +++++++++++++++++++++---- 1 file changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index 103e028e40a9..6988829efe27 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -16,12 +16,48 @@ Notes and warning blocks are used to draw attention to important information. Us - Use the following Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: * Surround the text with an opening and closing tag. * Use the following syntax to apply a style: -` -No need to add a prefix (Remember); the tag automatically provides one -` + ` + No need to add a prefix (Remember); the tag automatically provides one + ` + + The output: + + No need to add a prefix (Remember); the tag automatically provides one + -The output: +## Code Blocks - -No need to add a prefix (Remember); the tag automatically provides one - +Code blocks are used to display code examples or snippets. + +- In a Markdown document, use the `` tag and specify the language. + * Use the following syntax to apply a codeblock: + ` + {`npm start`} + ` + + The output: + + + {`npm start`} + + +- Use code style for filenames, directories, and paths. For example: Go to the `/docs/tutorials` directory. +- Use indentation to show the structure of the code. +- Use single backticks to enclose inline code. For example, `asyncapi new --example=tutorial.yml --no-tty` +- Remove trailing spaces in the code. +- For yaml document, enclose with triple backticks and specify `yaml`. (```) + * Use this syntax: + ` ```yaml + asyncapi: '2.5.0' + info: + title: Account Service + version: 1.0.0 + ``` ` + + * The output: + ```yaml + asyncapi: '2.5.0' + info: + title: Account Service + version: 1.0.0 + ``` From 705b144dde81e90058dcf7a2ca1aebf1846d24ab Mon Sep 17 00:00:00 2001 From: Karuna Tata <74637789+starlightknown@users.noreply.github.com> Date: Mon, 20 Feb 2023 20:05:02 +0530 Subject: [PATCH 03/15] Update docs/community/styleguide/formatting.md --- docs/community/styleguide/formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index 6988829efe27..b6b7ee4b1b77 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -1,6 +1,6 @@ --- title: Formatting style guide -description: This style guide explains about using correct formats when writing documenation. +description: This style guide explains using correct formats when writing documentation. weight: --- ## Documentation formatting From 0d6ec42d9a2f7a8dbdd07d2d08fa3f3baa5aa6e6 Mon Sep 17 00:00:00 2001 From: Karuna Tata <74637789+starlightknown@users.noreply.github.com> Date: Mon, 20 Feb 2023 20:18:16 +0530 Subject: [PATCH 04/15] Update formatting.md --- docs/community/styleguide/formatting.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index b6b7ee4b1b77..e9f2ed492f51 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -61,3 +61,9 @@ Code blocks are used to display code examples or snippets. title: Account Service version: 1.0.0 ``` +## Spacing + +Line spacing, or the amount of vertical space between lines of text in a paragraph, can aid or hinder reading. Adequate line spacing aids readers in navigating from the end of one line to the start of the next. + +- Use appropriate line spacing to make the content more readable. A single line spacing is usually sufficient for most cases. +- Use consistent indentation to show the hierarchy of the content. From dfce213b566ab70290ed63943caf4ae27cb8d9c1 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Sun, 11 Jun 2023 07:43:34 +0530 Subject: [PATCH 05/15] Update docs/community/styleguide/formatting.md Co-authored-by: Alejandra Quetzalli --- docs/community/styleguide/formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index e9f2ed492f51..282cec938bdb 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -1,6 +1,6 @@ --- title: Formatting style guide -description: This style guide explains using correct formats when writing documentation. +description: This guide illustrates the standards for formatting and writing our documentation. weight: --- ## Documentation formatting From bd03ef28f7d29f32460eeb133dfafdf4c9862f5b Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Sun, 11 Jun 2023 07:43:46 +0530 Subject: [PATCH 06/15] Update docs/community/styleguide/formatting.md Co-authored-by: Alejandra Quetzalli --- docs/community/styleguide/formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index 282cec938bdb..318e0ca1dec6 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -1,5 +1,5 @@ --- -title: Formatting style guide +title: Formatting description: This guide illustrates the standards for formatting and writing our documentation. weight: --- From 73c720de757b56d36afaf9d6d226cb45ab7ba52f Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Sun, 11 Jun 2023 07:44:04 +0530 Subject: [PATCH 07/15] Update docs/community/styleguide/formatting.md Co-authored-by: Alejandra Quetzalli --- docs/community/styleguide/formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index 318e0ca1dec6..d0d24f53fb48 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -25,7 +25,7 @@ Notes and warning blocks are used to draw attention to important information. Us No need to add a prefix (Remember); the tag automatically provides one -## Code Blocks +## Code blocks Code blocks are used to display code examples or snippets. From 5c4f62a64729e626cf4ee4b16cf6622fbc465309 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Sun, 11 Jun 2023 08:04:36 +0530 Subject: [PATCH 08/15] Update formatting.md --- docs/community/styleguide/formatting.md | 27 ++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index d0d24f53fb48..b0480eafe314 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -13,7 +13,7 @@ Notes and warning blocks are used to draw attention to important information. Us - Use short paragraphs or bullet points to convey the information. - Keep the language simple and direct. - Use an `>` in markdown to indicate the nature of the note or warning. -- Use the following Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: +- Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: * Surround the text with an opening and closing tag. * Use the following syntax to apply a style: ` @@ -42,10 +42,22 @@ Code blocks are used to display code examples or snippets. - Use code style for filenames, directories, and paths. For example: Go to the `/docs/tutorials` directory. -- Use indentation to show the structure of the code. +- Use a specific number of spaces for indentation, such as 2 or 4 spaces, consistently throughout the document. +- Indent the code properly to show the structure and hierarchy of the code. Each level of indentation should align with the appropriate scope. +- Avoid using tabs for indentation, as they may not render consistently across different platforms or text editors. +For example, when writing code in Markdown, use four spaces for each level of indentation: +``` +function myFunction() { + if (condition) { + console.log("Condition is true."); + } else { + console.log("Condition is false."); + } +} +``` - Use single backticks to enclose inline code. For example, `asyncapi new --example=tutorial.yml --no-tty` -- Remove trailing spaces in the code. -- For yaml document, enclose with triple backticks and specify `yaml`. (```) +- Remove any trailing spaces in the code. Trailing spaces can disrupt the readability and formatting of the code, so ensure they are removed. +- Use triple backticks to enclose YAML code blocks. Specify the language as "yaml" within the backticks. This syntax is specifically for displaying code blocks that contain YAML content. * Use this syntax: ` ```yaml asyncapi: '2.5.0' @@ -65,5 +77,10 @@ Code blocks are used to display code examples or snippets. Line spacing, or the amount of vertical space between lines of text in a paragraph, can aid or hinder reading. Adequate line spacing aids readers in navigating from the end of one line to the start of the next. -- Use appropriate line spacing to make the content more readable. A single line spacing is usually sufficient for most cases. +- Leave a blank line between paragraphs to visually separate them. This helps readers distinguish between different sections of content. +- For headings and subheadings, leave a single blank line above and below them to provide clear visual separation. +- Leave a single line spacing after bullet points or numbered lists to enhance readability. - Use consistent indentation to show the hierarchy of the content. +- Indentation can be achieved with either 2 or 4 spaces, depending on your preference or the coding style guidelines of your project. Choose one and use it consistently throughout the document. +- Use indentation to show nested content, such as code blocks, lists, or paragraphs within a list item. +- Indent code blocks by an additional level of indentation to differentiate them from regular text. From 4f3aeb9bf15acb254aabcff735ae4ad625f8aab8 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Sun, 11 Jun 2023 08:15:50 +0530 Subject: [PATCH 09/15] Update formatting.md --- docs/community/styleguide/formatting.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index b0480eafe314..3cdb59bab493 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -1,7 +1,7 @@ --- title: Formatting description: This guide illustrates the standards for formatting and writing our documentation. -weight: +weight: 2 --- ## Documentation formatting @@ -14,15 +14,16 @@ Notes and warning blocks are used to draw attention to important information. Us - Keep the language simple and direct. - Use an `>` in markdown to indicate the nature of the note or warning. - Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: - * Surround the text with an opening and closing tag. + * Surround the text you want to style with an opening tag and a closing tag. + * It is important to note that you don't need to include the word "Remember" within the tags. The tag itself automatically provides the necessary styling. * Use the following syntax to apply a style: ` - No need to add a prefix (Remember); the tag automatically provides one + No need to add a prefix; the tag automatically provides one ` The output: - No need to add a prefix (Remember); the tag automatically provides one + No need to add a prefix; the tag automatically provides one ## Code blocks From 7401a66992b8ea1dd326da54d7bd12b78b609e2b Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Thu, 15 Jun 2023 20:26:21 -0700 Subject: [PATCH 10/15] grammar fixes --- docs/community/styleguide/formatting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/community/styleguide/formatting.md b/docs/community/styleguide/formatting.md index 3cdb59bab493..e3ecfcde8e41 100644 --- a/docs/community/styleguide/formatting.md +++ b/docs/community/styleguide/formatting.md @@ -15,7 +15,7 @@ Notes and warning blocks are used to draw attention to important information. Us - Use an `>` in markdown to indicate the nature of the note or warning. - Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: * Surround the text you want to style with an opening tag and a closing tag. - * It is important to note that you don't need to include the word "Remember" within the tags. The tag itself automatically provides the necessary styling. + * Note that the word 'Remember' does not need to be included within the tags, as it automatically provides the necessary styling. * Use the following syntax to apply a style: ` No need to add a prefix; the tag automatically provides one @@ -43,7 +43,7 @@ Code blocks are used to display code examples or snippets. - Use code style for filenames, directories, and paths. For example: Go to the `/docs/tutorials` directory. -- Use a specific number of spaces for indentation, such as 2 or 4 spaces, consistently throughout the document. +- Choose a consistent number of spaces for indentation, such as 2 or 4 spaces, and use it consistently throughout the document. - Indent the code properly to show the structure and hierarchy of the code. Each level of indentation should align with the appropriate scope. - Avoid using tabs for indentation, as they may not render consistently across different platforms or text editors. For example, when writing code in Markdown, use four spaces for each level of indentation: From dfa1ec7b83491d2796dbf90e8139c41b8d1ea6c5 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Tue, 11 Jul 2023 08:53:02 +0530 Subject: [PATCH 11/15] Rename docs/community/styleguide/formatting.md to pages/docs/community/styleguide/formatting.md --- {docs => pages/docs}/community/styleguide/formatting.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {docs => pages/docs}/community/styleguide/formatting.md (100%) diff --git a/docs/community/styleguide/formatting.md b/pages/docs/community/styleguide/formatting.md similarity index 100% rename from docs/community/styleguide/formatting.md rename to pages/docs/community/styleguide/formatting.md From ff80d1e9abb1b2965bf9d60565a37200d4ccab5c Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Tue, 11 Jul 2023 09:02:13 +0530 Subject: [PATCH 12/15] Update formatting.md --- pages/docs/community/styleguide/formatting.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pages/docs/community/styleguide/formatting.md b/pages/docs/community/styleguide/formatting.md index e3ecfcde8e41..19be0002c4b9 100644 --- a/pages/docs/community/styleguide/formatting.md +++ b/pages/docs/community/styleguide/formatting.md @@ -5,6 +5,8 @@ weight: 2 --- ## Documentation formatting +Documentation formatting refers to how the document appears on the page and how the content is organized, which includes font selection, font size and presentation (such as bold or italics), spacing, margins, alignment, columns, indentation, and lists. Formatting is crucial because it helps the reader perceive the information and makes it more accessible. + ### Notes and warning blocks Notes and warning blocks are used to draw attention to important information. Use the following markdown features when necessary: @@ -79,7 +81,7 @@ function myFunction() { Line spacing, or the amount of vertical space between lines of text in a paragraph, can aid or hinder reading. Adequate line spacing aids readers in navigating from the end of one line to the start of the next. - Leave a blank line between paragraphs to visually separate them. This helps readers distinguish between different sections of content. -- For headings and subheadings, leave a single blank line above and below them to provide clear visual separation. +- For headings and subheadings, leave a single blank line before and after them to provide clear visual separation. - Leave a single line spacing after bullet points or numbered lists to enhance readability. - Use consistent indentation to show the hierarchy of the content. - Indentation can be achieved with either 2 or 4 spaces, depending on your preference or the coding style guidelines of your project. Choose one and use it consistently throughout the document. From 77b7e7167cf210cb392048e118bb59c431c57a0b Mon Sep 17 00:00:00 2001 From: akshatnema <20bcs022@iiitdmj.ac.in> Date: Tue, 11 Jul 2023 12:50:33 +0530 Subject: [PATCH 13/15] Added _section.md for styleguide --- pages/docs/community/styleguide/_section.md | 4 ++++ pages/docs/community/styleguide/formatting.md | 10 ++++++---- 2 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 pages/docs/community/styleguide/_section.md diff --git a/pages/docs/community/styleguide/_section.md b/pages/docs/community/styleguide/_section.md new file mode 100644 index 000000000000..412e7f0424b2 --- /dev/null +++ b/pages/docs/community/styleguide/_section.md @@ -0,0 +1,4 @@ +--- +title: 'Styleguide' +weight: 10 +--- \ No newline at end of file diff --git a/pages/docs/community/styleguide/formatting.md b/pages/docs/community/styleguide/formatting.md index 19be0002c4b9..9e2d6a6c589c 100644 --- a/pages/docs/community/styleguide/formatting.md +++ b/pages/docs/community/styleguide/formatting.md @@ -1,7 +1,7 @@ --- title: Formatting description: This guide illustrates the standards for formatting and writing our documentation. -weight: 2 +weight: 11 --- ## Documentation formatting @@ -33,10 +33,12 @@ Notes and warning blocks are used to draw attention to important information. Us Code blocks are used to display code examples or snippets. - In a Markdown document, use the `` tag and specify the language. - * Use the following syntax to apply a codeblock: - ` + Use the following syntax to apply a codeblock: + ``` + {`npm start`} - ` + + ``` The output: From 0b89fe4f61c37aea1400ac3c19505237262caf80 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Mon, 27 Nov 2023 17:00:54 -0800 Subject: [PATCH 14/15] fix title --- pages/docs/community/styleguide/_section.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/community/styleguide/_section.md b/pages/docs/community/styleguide/_section.md index 412e7f0424b2..40b7635f13d5 100644 --- a/pages/docs/community/styleguide/_section.md +++ b/pages/docs/community/styleguide/_section.md @@ -1,4 +1,4 @@ --- -title: 'Styleguide' +title: 'Style Guide' weight: 10 --- \ No newline at end of file From 8151476fa160f93f7aa3ee7777281d79a16720a8 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Thu, 7 Mar 2024 16:04:10 +0530 Subject: [PATCH 15/15] Update formatting.md --- pages/docs/community/styleguide/formatting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/community/styleguide/formatting.md b/pages/docs/community/styleguide/formatting.md index 9e2d6a6c589c..688e7fd761aa 100644 --- a/pages/docs/community/styleguide/formatting.md +++ b/pages/docs/community/styleguide/formatting.md @@ -15,7 +15,7 @@ Notes and warning blocks are used to draw attention to important information. Us - Use short paragraphs or bullet points to convey the information. - Keep the language simple and direct. - Use an `>` in markdown to indicate the nature of the note or warning. -- Use the following syntax to apply a style. Currently our documenation supports **Remember** ``: +- Use the following syntax to apply a style. Currently our documentation supports **Remember** ``: * Surround the text you want to style with an opening tag and a closing tag. * Note that the word 'Remember' does not need to be included within the tags, as it automatically provides the necessary styling. * Use the following syntax to apply a style: @@ -33,7 +33,7 @@ Notes and warning blocks are used to draw attention to important information. Us Code blocks are used to display code examples or snippets. - In a Markdown document, use the `` tag and specify the language. - Use the following syntax to apply a codeblock: + Use the following syntax to apply a code block: ``` {`npm start`} @@ -80,7 +80,7 @@ function myFunction() { ``` ## Spacing -Line spacing, or the amount of vertical space between lines of text in a paragraph, can aid or hinder reading. Adequate line spacing aids readers in navigating from the end of one line to the start of the next. +Line spacing, or the vertical space between lines of text in a paragraph, can aid or hinder reading. Adequate line spacing aids readers in navigating from the end of one line to the start of the next. - Leave a blank line between paragraphs to visually separate them. This helps readers distinguish between different sections of content. - For headings and subheadings, leave a single blank line before and after them to provide clear visual separation.