docs/reference: amend custom embeds docs (#74)

Correct link to discord message docs
Document YAML usage
Give a more complex example with footer text instead of description
Add unicode escape sequence to escape table
Replace example image to reflect new examples in both YAML and JSON
Link to Wikipedia pages for YAML/JSON syntax -- we only have a (very)
simplified/incomplete description here
Reword existing usage docs

Signed-off-by: Galen CC <[email protected]>

Author: galen8183

content/docs/reference/custom-embeds.md

@@ -17,7 +17,7 @@ documentation](https://discord.com/developers/docs/resources/channel#embed-objec
 
 {{< callout context="note" title="Note: Custom Commands use Custom Syntax" icon="outline/info-circle" >}}
 
-Custom Embeds with the `-customembed` command don't work in custom commands. If you want to know how you can use embeds
+Custom Embeds with the `customembed` command don't work in custom commands. If you want to know how you can use embeds
 in custom commands, scroll down to [Embeds in Custom Commands](#embeds-in-custom-commands).
 
 {{< /callout >}}
@@ -28,56 +28,84 @@ One method of sending an embed with YAGPDB is using the command `customembed` (o
 
 ### Create embeds by hand
 
-YAGPDB accepts embeds in JSON following the rules of Discord's [Embed Object] structure.
+YAGPDB accepts embeds in JSON or YAML following the rules of Discord's [Embed Object] structure.
 
-[Embed Object]: https://discord.com/developers/docs/resources/message#embed-object.
+[Embed Object]: https://discord.com/developers/docs/resources/message#embed-object
 
-```javascript
-{ "title": "This is my title", "description": "This is my description." }
+![An Example of the Custom Embed Command](custom_embed_example.png)
+
+#### Using YAML
+
+```yaml
+title: This is my title
+footer:
+	text: This is my footer text.
 ```
 
-The output of this would look like the following:
+YAML input is formatted as a list of names with associated values for each part of the embed. In this example I start
+with a name (title) and the associated value (This is my title) after a semicolon. On a new line, we have another name
+(footer), this time with another list of name-value pairs as the value. An indent indicates that the name-value pair
+(text: This is ...) is part of the value of the footer.
 
-![An Example of the Custom Embed Command](custom_embed_example.png)
+##### The syntax of YAML
+
+[YAML] has an intuitive, lenient syntax. Most parts of the embed are simple name-value pairs (or nested name-value
+maps like in the footer shown above). New lines separate each pair, unless the next line is indented to indicate that
+that line is the value. Strings (text) can be included as-is without quotes, unless the text contains special characters
+like `:`, in which case single quotes (`'`) or double quotes (`"`) may be used. Double quotes allow backslash-escapes to
+add newlines, double quotes, and more.
+
+[YAML]: https://en.wikipedia.org/wiki/YAML#Syntax
+
+#### Using JSON
+
+```javascript
+{ "title": "This is my title", "footer": { "text": "This is my footer text." } }
+```
+
+As shown in the example above, I start my object (the embed) with a curly brace. Like YAML, we then have a name (title)
+and the value for that name (This is my title). We separate each name-value pair with a comma. Then we have something
+similar, but with another object as the value. Within that object we have a name-value pair with the same format as the
+title, this time for the footer text. In the end we close the objects (footer and embed) with more curly braces.
 
-Let's break this down: We start of with the customembed command `-ce`. After this, I start my object (the embed) with a
-curly brace. Then we have the name of the object (title) and the value of it (This is my title). We separate data with
-commas. After that we have the same thing again, but for the description. In the end we close the object (embed) with
-another curly brace.
+##### The syntax of JSON
 
-You can add the multiple objects to this, but keep in mind that Discord limits your message to 2000 characters.
+[JSON]'s syntax is also quite simple. Objects start with an opening curly brace (`{`) and end with a closing curly brace
+(`}`). Between these, you can add names and their associated values. Each name-value pair is separated by a comma (`,`).
+Around strings (text) you wrap two quotation marks (`""`), but nothing around integers (whole numbers) or booleans
+(`true` or `false` values). You can play around with this a bit.
 
-#### The syntax of JSON
+Some special characters need to be prefixed with a backslash in strings to indicate that they aren't part of the JSON
+syntax:
 
-The syntax of json is pretty easy. You start off with a curly brace (`{`) and end with a curly brace (`}`). Between
-this, you can add names and their according values. Data (a name and a value) get separated by commas (`,`) . Around
-strings (text) you wrap two quotation marks (`""`), but nothing around integers (whole numbers) or booleans (true or
-false statements). You can play around with this a bit.
+| Special character   | Escaped input |
+| ------------------  | ------------- |
+| Quotation mark (")  | \\"           |
+| Backslash (\\)      | \\\\          |
+| Slash (/)           | \\/           |
+| Backspace           | \b            |
+| Form feed           | \f            |
+| New line            | \n            |
+| Carriage return     | \r            |
+| Horizontal tab      | \t            |
+| [Unicode character] | \uXXXX        |
 
-| Special character  | Escaped output |
-| ------------------ | -------------- |
-| Quotation mark (") | \\"            |
-| Backslash (\\)     | \\\\           |
-| Slash (/)          | \\/            |
-| Backspace          | \b             |
-| Form feed          | \f             |
-| New line           | \n             |
-| Carriage return    | \r             |
-| Horizontal tab     | \t             |
+[JSON]: https://en.wikipedia.org/wiki/JSON#Syntax
+[Unicode character]: https://en.wikipedia.org/wiki/List_of_Unicode_characters
 
 ### Create embeds with a generator
 
 Creating embeds with a generator can be more difficult if you don't need any difficult features. If you want your embed
-to be super shiny, you can use [this embed generator](https://leovoel.github.io/embed-visualizer/). YAGPDB does not use
-the first part of its code, so you have to remove the following:
+to be super shiny, you can use [an embed generator](https://leovoel.github.io/embed-visualizer/). The customembed
+command only sends an embed, so you'll need to remove everything around it:
 
 ````javascript
 {
-  "content": "this `supports` __a__ **subset** *of* ~~markdown~~ 😃 ```js\nfunction foo(bar) {\n  console.log(bar);\n}\n\nfoo(1);```",
+  "content": "...",
   "embed":
 ````
 
-and the last curly brace (`}`). After this you can just copy and paste it into Discord:
+and the last curly brace (`}`). After this you can copy and paste it after the `ce` command:
 
 ![Result of the Embed Generator](embed_generator_result.png)