Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixed styleguide table example #4882

Merged
merged 5 commits into from
Oct 9, 2023
Merged

Fixed styleguide table example #4882

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ad070e6
Fixed styleguide table example
djw-m Oct 5, 2023
338140f
Other format fixes
djw-m Oct 5, 2023
f096917
Add images for clarity on code blocks
djw-m Oct 5, 2023
843f3c4
A few additions and simplifications to code syntax
josh-heyer Oct 6, 2023
77e2454
Removed images
djw-m Oct 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 87 additions & 21 deletions advocacy_docs/community/contributing/styleguide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand All @@ -400,7 +395,11 @@ Addresses are relative. In these examples of links to topics, “folder” means

**Example:**

``# Anchor: <a id="flags-max-offset"></a>`--max-offset` # Link: [--max-offset](#flags-max-offset)``
```markdown
Anchor: <a id="flags-max-offset"></a> `--max-offset`

Link: [--max-offset](#flags-max-offset)
```


## Admonitions: notes, tips, and warnings
Expand Down Expand Up @@ -433,15 +432,41 @@ 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.

### Nesting inline code

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.

### Code blocks

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.`
````
This is a sample line of text.

```
{% include copy-clipboard.html %}
~~~shell
$ go get -u github.com/lib/pq
~~~
```
````
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.

Expand All @@ -455,21 +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,

`
```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)
```

* **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
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)
```
````

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
------
Expand All @@ -487,9 +543,19 @@ 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"`
```

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:
Expand Down