From b7ec22539e7373831016827a496a5868655f3cbb Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Thu, 7 Mar 2024 16:09:23 +0530 Subject: [PATCH 1/4] add formatting styleguide --- docs/style-guide/formatting.md | 92 ++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/style-guide/formatting.md diff --git a/docs/style-guide/formatting.md b/docs/style-guide/formatting.md new file mode 100644 index 000000000..e0c10bce5 --- /dev/null +++ b/docs/style-guide/formatting.md @@ -0,0 +1,92 @@ +--- +title: Formatting +description: This guide illustrates the standards for formatting and writing our documentation. +weight: 11 +--- +## 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: + +- 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 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: + ` + No need to add a prefix; the tag automatically provides one + ` + + The output: + + No need to add a prefix; the tag automatically provides one + + +## Code blocks + +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 code block: + ``` + + {`npm start`} + + ``` + + The output: + + + {`npm start`} + + +- Use code style for filenames, directories, and paths. For example: Go to the `/docs/tutorials` directory. +- 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: +``` +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 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' + info: + title: Account Service + version: 1.0.0 + ``` ` + + * The output: + ```yaml + asyncapi: '2.5.0' + info: + title: Account Service + version: 1.0.0 + ``` + +## Spacing + +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. +- 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. \ No newline at end of file From ae60c931f17511954f06cc46977acd5898fceb3c Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Fri, 8 Mar 2024 17:19:03 +0530 Subject: [PATCH 2/4] Update docs/style-guide/formatting.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/formatting.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/style-guide/formatting.md b/docs/style-guide/formatting.md index e0c10bce5..378ebedff 100644 --- a/docs/style-guide/formatting.md +++ b/docs/style-guide/formatting.md @@ -3,6 +3,7 @@ title: Formatting description: This guide illustrates the standards for formatting and writing our documentation. weight: 11 --- + ## 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. From 784d3674843d962f5e4902a0f79973667723c00e Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Fri, 8 Mar 2024 17:19:10 +0530 Subject: [PATCH 3/4] Update docs/style-guide/formatting.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/formatting.md b/docs/style-guide/formatting.md index 378ebedff..6127eb612 100644 --- a/docs/style-guide/formatting.md +++ b/docs/style-guide/formatting.md @@ -6,7 +6,7 @@ weight: 11 ## 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. +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 helps the reader perceive the information and makes it more accessible. ### Notes and warning blocks From 4f0a96b41afb35f2c9688051e36d47cd7df07b75 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Fri, 8 Mar 2024 17:19:56 +0530 Subject: [PATCH 4/4] Update docs/style-guide/formatting.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/formatting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/style-guide/formatting.md b/docs/style-guide/formatting.md index 6127eb612..fc8cf5c0e 100644 --- a/docs/style-guide/formatting.md +++ b/docs/style-guide/formatting.md @@ -82,12 +82,12 @@ function myFunction() { ## Spacing -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. +Line spacing, or the vertical space between lines of text in a paragraph, can aid or hinder reading. Adequate line spacing helps readers navigate 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. +- For headings and subheadings, leave a 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. - 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. \ No newline at end of file +- Indent code blocks by an additional indentation level to differentiate them from regular text. \ No newline at end of file