From ad070e63a66e0e620fbc69f06873b4561a7d3023 Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan <126472455+djw-m@users.noreply.github.com> Date: Thu, 5 Oct 2023 11:50:51 +0100 Subject: [PATCH 1/5] Fixed styleguide table example Styleguide table example lacked wrapping --- advocacy_docs/community/contributing/styleguide.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index 6ea7ba2c3d9..89a8b419393 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -487,7 +487,10 @@ We don’t use outer pipes. Example: ``` -Term | Description | Example ----------|-----------------------------|---------------- `term_1` | This is a description. | `3.14` `term_2` | This is also a description. | `"lola mcdog"` +Term | Description | Example +----------|-----------------------------|---------------- +`term_1` | This is a description. | `3.14` +`term_2` | This is also a description. | `"lola mcdog"` ``` ## Lists From 338140fa119c0b67604d14fe2a63b3ab27c661c4 Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan <126472455+djw-m@users.noreply.github.com> Date: Thu, 5 Oct 2023 12:24:46 +0100 Subject: [PATCH 2/5] Other format fixes --- .../community/contributing/styleguide.mdx | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index 89a8b419393..5f94c90706e 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -377,13 +377,8 @@ Link capitalization can be either title- or sentence-case: Addresses are relative. In these examples of links to topics, “folder” means the folder in the repo such as the product folder or the guide folder. For the destination topic, use the name of the file without the .mdx extension. If the destination includes a topic\_identifier (sub-section of a file), include the topic\_identifier prefixed with a # sign, such as in “/09\_controlling\_logging/#enabling_syslog.” -| | | | | | -| --- | --- | --- | --- | --- | | **Link type** | **Syntax** | **Example** | **Source path** | **Destination path** | - -| | | | | | | --- | --- | --- | --- | --- | -| **Link type** | **Syntax** | **Example** | **Source path** | **Destination path** | | Another topic in the same folder | `[here](file_name)` | `[Using the EFM Utility](07_using_efm_utility/#using_efm_utility)` | /efm/4.2/efm\_user/07\_using_efm.mdx | /efm/4.2/efm\_user/07\_using\_efm\_utility.mdx | | Another topic in a different folder at the same level | `[here](../dest_folder_name/file_name)` | \[The ERD Tool\](../pem\_ent\_feat/04\_pem\_erd_tool/) | /pem/8/pem\_rel\_notes/08\_810\_rel_notes.mdx | /pem/8/pem\_ent\_feat04\_pem\_erd_tool/ | | Another topic in a different folder at a different level | `[here](../../folder_name/file_name`) | \[Enabling syslog Log File Entries\](../../09\_controlling\_logging/#enabling_syslog) | /efm/4.2/efm\_user/04\_configuring\_efm/01\_cluster_properties/index.mdx | /efm/4.2/efm\_user/09\_controlling\_logging.mdx/enabling\_syslog | @@ -458,10 +453,27 @@ SQL code samples are broken into two sections: commands and responses. * **Responses** (e.g., retrieved tables) add (_ _ 0UTPUT _ _) on a line between the command and the output, you'll get highlights for the code but not the output. For example, ` - ```sql SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; __OUTPUT__ slot_name | slot_type | database | active -------------+-----------+-----------+-------- xdb_47877_5 | logical | MMRnode_a | t xdb_47878_5 | logical | MMRnode_b | t xdb_47879_5 | logical | MMRnode_c | t (3 rows) ``` ` - -``` -sql SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; __OUTPUT__ slot_name | slot_type | database | active -------------+-----------+-----------+-------- xdb_47877_5 | logical | MMRnode_a | t xdb_47878_5 | logical | MMRnode_b | t xdb_47879_5 | logical | MMRnode_c | t (3 rows) + ```sql + SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; + __OUTPUT__ + slot_name | slot_type | database | active + ------------+-----------+-----------+-------- + xdb_47877_5 | logical | MMRnode_a | t + xdb_47878_5 | logical | MMRnode_b | t + xdb_47879_5 | logical | MMRnode_c | t + (3 rows) + ``` + ` + +```sql +SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; +__OUTPUT__ +slot_name | slot_type | database | active +------------+-----------+-----------+-------- +xdb_47877_5 | logical | MMRnode_a | t +xdb_47878_5 | logical | MMRnode_b | t +xdb_47879_5 | logical | MMRnode_c | t +(3 rows) ``` From f096917d24f826fbfdc5d8104aef5ee6b82b01df Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan Date: Thu, 5 Oct 2023 13:40:31 +0100 Subject: [PATCH 3/5] Add images for clarity on code blocks Signed-off-by: Dj Walker-Morgan --- .../contributing/images/samplecodeblock.png | 3 ++ .../contributing/images/sqlcodeblock.png | 3 ++ .../community/contributing/styleguide.mdx | 43 ++++++++++++------- 3 files changed, 33 insertions(+), 16 deletions(-) create mode 100644 advocacy_docs/community/contributing/images/samplecodeblock.png create mode 100644 advocacy_docs/community/contributing/images/sqlcodeblock.png diff --git a/advocacy_docs/community/contributing/images/samplecodeblock.png b/advocacy_docs/community/contributing/images/samplecodeblock.png new file mode 100644 index 00000000000..82c42373f3d --- /dev/null +++ b/advocacy_docs/community/contributing/images/samplecodeblock.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9bb13f91cacec973ca7280672e2cdb05e965912a7d0e4f98a517ca9fa5af962e +size 48987 diff --git a/advocacy_docs/community/contributing/images/sqlcodeblock.png b/advocacy_docs/community/contributing/images/sqlcodeblock.png new file mode 100644 index 00000000000..b39c28acd3b --- /dev/null +++ b/advocacy_docs/community/contributing/images/sqlcodeblock.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3bb0f5c193aa97abf86afa1911543ccb85f9284d26abe875938280b1c3e32b61 +size 77171 diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index 5f94c90706e..64e2b9746fd 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -436,7 +436,21 @@ Example: The `CREATE TABLE` statement creates a new table in a database. Code blocks provide executable code samples, marked with an opening and closing set of three backticks (` ``` `). Code blocks can support syntax highlighting if you add the language name immediately after the first line of backticks. Use one returned line before and after a code block for better Markdown readability. For example: -`This is a sample line of text. ``` {% include copy-clipboard.html %} ~~~shell $ go get -u github.com/lib/pq ~~~ ``` This is more sample text.` +![Sample Code Block](images/samplecodeblock.png) + +Which results in: + +This is a sample line of text. + +``` +{% include copy-clipboard.html %} +~~~shell +$ go get -u github.com/lib/pq +~~~ +``` + +This is more sample text. + Use syntax highlighting for configuration file , shell, and SQL commands, where appropriate, as follows. @@ -452,7 +466,10 @@ SQL code samples are broken into two sections: commands and responses. * **Responses** (e.g., retrieved tables) add (_ _ 0UTPUT _ _) on a line between the command and the output, you'll get highlights for the code but not the output. For example, - ` + ![SQL Code Block with Output](images/sqlcodeblock.png) + + Results in + ```sql SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; __OUTPUT__ @@ -462,20 +479,7 @@ SQL code samples are broken into two sections: commands and responses. xdb_47878_5 | logical | MMRnode_b | t xdb_47879_5 | logical | MMRnode_c | t (3 rows) - ``` - ` - -```sql -SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; -__OUTPUT__ -slot_name | slot_type | database | active -------------+-----------+-----------+-------- -xdb_47877_5 | logical | MMRnode_a | t -xdb_47878_5 | logical | MMRnode_b | t -xdb_47879_5 | logical | MMRnode_c | t -(3 rows) -``` - + ``` ` **Configuration file samples** @@ -505,6 +509,13 @@ Term | Description | Example `term_2` | This is also a description. | `"lola mcdog"` ``` +Resulting in + +Term | Description | Example +----------|-----------------------------|---------------- +`term_1` | This is a description. | `3.14` +`term_2` | This is also a description. | `"lola mcdog"` + ## Lists EDB docs uses two types of lists: From 843f3c46df387bb83d81a370ad01d402355d63bc Mon Sep 17 00:00:00 2001 From: Josh Heyer Date: Fri, 6 Oct 2023 15:30:31 +0000 Subject: [PATCH 4/5] A few additions and simplifications to code syntax --- .../community/contributing/styleguide.mdx | 74 ++++++++++++++----- 1 file changed, 57 insertions(+), 17 deletions(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index 64e2b9746fd..577473e3ad0 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -346,9 +346,9 @@ If you need to enter a `value in a field`, type the `ls` or `dd` command, add a See [Code](#code) for more information. -### Italics (*_text_*) +### Italics (`_text_`) -Use for book titles and first instance of terms. Do not use Italics for keywords. +Use for book titles and first instance of terms. Do not use _Italics_ for keywords. ### Underline @@ -395,7 +395,11 @@ Addresses are relative. In these examples of links to topics, “folder” means **Example:** - ``# Anchor: `--max-offset` # Link: [--max-offset](#flags-max-offset)`` + ```markdown + Anchor: `--max-offset` + + Link: [--max-offset](#flags-max-offset) + ``` ## Admonitions: notes, tips, and warnings @@ -428,18 +432,19 @@ Code can be shown inline or as a code block. ### Inline code -Inline `code` has `back-ticks (``) around` it and is used when referring to code, commands, or other technical syntax within a sentence. +Inline `code` has back-ticks around it (`` `code` ``) and is used when referring to code, commands, or other technical syntax within a sentence. Example: The `CREATE TABLE` statement creates a new table in a database. -### Code blocks +### Nesting inline code -Code blocks provide executable code samples, marked with an opening and closing set of three backticks (` ``` `). Code blocks can support syntax highlighting if you add the language name immediately after the first line of backticks. Use one returned line before and after a code block for better Markdown readability. For example: +To format code that includes back-ticks, add additional back-ticks to demarcate: ``` `` \echo `date` `` ``` - note we need spaces to separate the demarcation from the code in this example. -![Sample Code Block](images/samplecodeblock.png) +### Code blocks -Which results in: +Code blocks provide executable code samples, marked with an opening and closing set of three backticks (` ``` `). Code blocks can support syntax highlighting if you add the language name immediately after the first line of backticks. Use one returned line before and after a code block for better Markdown readability. For example: +```` This is a sample line of text. ``` @@ -448,8 +453,19 @@ This is a sample line of text. $ go get -u github.com/lib/pq ~~~ ``` +```` +Which results in: -This is more sample text. +> This is a sample line of text. +> +> ``` +> {% include copy-clipboard.html %} +> ~~~shell +> $ go get -u github.com/lib/pq +> ~~~ +> ``` +> +> This is more sample text. Use syntax highlighting for configuration file , shell, and SQL commands, where appropriate, as follows. @@ -464,28 +480,52 @@ SQL code samples are broken into two sections: commands and responses. * **Commands** (e.g., `SELECT`, `CREATE TABLE`) begin with ` ```sql` followed by a line break. The first character of the next line should be the terminal marker `>`. Capitalize commands properly. Use only one command per code sample. -* **Responses** (e.g., retrieved tables) add (_ _ 0UTPUT _ _) on a line between the command and the output, you'll get highlights for the code but not the output. For example, +* **Responses** (e.g., retrieved tables) add (`__OUTPUT__`) on a line between the command and the output, you'll get highlights for the code but not the output. For example, - ![SQL Code Block with Output](images/sqlcodeblock.png) - - Results in - + ```` ```sql SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; - __OUTPUT__ + __OUTPUT_ slot_name | slot_type | database | active ------------+-----------+-----------+-------- xdb_47877_5 | logical | MMRnode_a | t xdb_47878_5 | logical | MMRnode_b | t xdb_47879_5 | logical | MMRnode_c | t (3 rows) - ``` ` + ``` + ```` + + Results in + + > ```sql + > SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; + > __OUTPUT__ + > slot_name | slot_type | database | active + > ------------+-----------+-----------+-------- + > xdb_47877_5 | logical | MMRnode_a | t + > xdb_47878_5 | logical | MMRnode_b | t + > xdb_47879_5 | logical | MMRnode_c | t + > (3 rows) + > ``` **Configuration file samples** For files that have key-value pairs use ` ```ini`. For example: -` ```ini promotable=false auto.reconfigure=false ``` ` +```` +```ini +promotable=false +auto.reconfigure=false +``` +```` + +Which results in: + +> ```ini +> promotable=false +> auto.reconfigure=false +> ``` + Tables ------ From 77e2454f6c7da750884a020331e71b1c8c6d476f Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan Date: Fri, 6 Oct 2023 16:37:55 +0100 Subject: [PATCH 5/5] Removed images Signed-off-by: Dj Walker-Morgan --- .../community/contributing/images/samplecodeblock.png | 3 --- advocacy_docs/community/contributing/images/sqlcodeblock.png | 3 --- 2 files changed, 6 deletions(-) delete mode 100644 advocacy_docs/community/contributing/images/samplecodeblock.png delete mode 100644 advocacy_docs/community/contributing/images/sqlcodeblock.png diff --git a/advocacy_docs/community/contributing/images/samplecodeblock.png b/advocacy_docs/community/contributing/images/samplecodeblock.png deleted file mode 100644 index 82c42373f3d..00000000000 --- a/advocacy_docs/community/contributing/images/samplecodeblock.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:9bb13f91cacec973ca7280672e2cdb05e965912a7d0e4f98a517ca9fa5af962e -size 48987 diff --git a/advocacy_docs/community/contributing/images/sqlcodeblock.png b/advocacy_docs/community/contributing/images/sqlcodeblock.png deleted file mode 100644 index b39c28acd3b..00000000000 --- a/advocacy_docs/community/contributing/images/sqlcodeblock.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3bb0f5c193aa97abf86afa1911543ccb85f9284d26abe875938280b1c3e32b61 -size 77171