DS-730 docs: Revise Text Editor section

assets/scss/_styles_project.scss

@@ -50,4 +50,20 @@ dd {
       padding-top: 15px;
     }
   }
+}
+
+// Override Bootstrap's kbd styles
+kbd {
+  display: inline-block;
+  background: #f5f5f5;
+  border: solid 1px #b5c6d2;
+  border-bottom-color: #97afbf;
+  box-shadow: inset 0 -1px 0 #97afbf;
+  font-family: Monaco,Menlo,Consolas,"Roboto Mono","Courier New","Ubuntu Mono",monospace;
+  font-size: .8em;
+  padding: .25em .5em;
+  line-height: 1em;
+  vertical-align: middle;
+  border-radius: 3px;
+  color: inherit;
 }

content/en/docs/user-documentation/text-editor/_index.md

@@ -2,15 +2,19 @@
 title: "Text Editor"
 weight: 1
 description: >
-  Some fields in YMCA Website Services allow you to format your text like in a Word doc. This feature is called [the Text Editor or WYSIWYG (What Your See Is What You Get)](https://ckeditor.com).
+  Some fields in YMCA Website Services allow you to format your text with a WYSIWYG (What Your See Is What You Get) editor.
 ---
 
-![blog-description__text-editor|690x307](../../../../../assets/img/dd630632ed4ea5876a15d65709946e420ffb84d1.png)
+![An example of the WYSIWYG text editor.](text-editor--example.png)
 
-*The description field inside a blog is an example of the WYISWYG Editor in action.*
+This tool allows you the flexibility to format content however you want within a certain container or area.
 
-[If you have worked in a Content Management System](https://www.optimizely.com/optimization-glossary/content-management-system/) like Drupal, Wordpress or Joomla!, you are likely familiar with what a text editor does. This tool allows you the flexibility to format content however you want within a certain container or area.
+Bundled with the Drupal core and the distribution, [CKEditor](https://ckeditor.com/ckeditor-5/demo/feature-rich/) provides a number of different buttons for styling and formatting, as well as a Source editor if you are so inclined to edit HTML directly.
 
-![blog-description_text-editor-example|690x385](../../../../../assets/img/4e7d30e968474e737d679c2f2a9081a91bc8d9c0.png)
+CKEditor has been [upgraded to version 5](https://www.drupal.org/node/3308362) as of Drupal 10, and is a big improvement over CKEditor 4 — the linking experience is much smoother, uploading images is much faster, and more.
 
-[YMCA Website Services's text editor (CKEditor)](https://ckeditor.com/ckeditor-4/demo/#article) provides a number of different buttons for styling and formatting, as well as a Source editor if you are so inclined to use HTML.
+For more info on CKEditor 5, check out these resources (not all features may be implemented in the distribution):
+
+- [Five Can’t-Miss Articles on CKEditor 5 in Drupal (ImageX Blog)](https://imagexmedia.com/blog/five-cant-miss-articles-on-ckeditor-5-in-drupal)
+- [CKEditor 5 in Drupal 10: What is there to be excited about? (DrupalCon Portland 2022)](https://www.youtube.com/watch?v=YwDFCLaQVbY)
+- [Drupal 10 launched: taking content editing to the next level with CKEditor 5 (CKEditor Blog)](https://ckeditor.com/blog/drupal-10-launched-taking-content-editing-to-the-next-level-with-ckeditor-5/)

content/en/docs/user-documentation/text-editor/adding-documents.md → content/en/docs/user-documentation/text-editor/adding-documents/_index.md

@@ -1,7 +1,12 @@
 ---
-title: 'Adding/Embedding Documents'
+title: 'CKEditor 4: Adding/Embedding Documents'
+weight: 99
 ---
 
+{{< alert color="warning" >}}
+This document applies to the legacy WYSIWYG editor, CKEditor 4. See [Adding Media](../adding-media/) for updated instructions.
+{{< /alert >}}
+
 YMCA Website Services allows you to upload and embed documents directly into a block of text, either from your computer or from the YMCA Website Services media library and browser.
 
 {{< youtube id=5w-_bpHtTLI >}}

content/en/docs/user-documentation/text-editor/adding-embedding-videos.md → content/en/docs/user-documentation/text-editor/adding-embedding-videos/_index.md

@@ -1,7 +1,12 @@
 ---
-title: 'Adding and Embedding Videos'
+title: 'CKEditor 4: Adding and Embedding Videos'
+weight: 99
 ---
 
+{{< alert color="warning" >}}
+This document applies to the legacy WYSIWYG editor, CKEditor 4. See [Adding Media](../adding-media/) for updated instructions.
+{{< /alert >}}
+
 # Adding/Embedding Videos with the YMCA Website Services Text Editor
 YMCA Website Services allows you to upload and embed images directly into a block of text, either from your computer or from the YMCA Website Services media library and browser.
 

content/en/docs/user-documentation/text-editor/adding-images.md → content/en/docs/user-documentation/text-editor/adding-images/_index.md

@@ -1,7 +1,12 @@
 ---
-title: 'Adding Images'
+title: 'CKEditor 4: Adding Images'
+weight: 99
 ---
 
+{{< alert color="warning" >}}
+This document applies to the legacy WYSIWYG editor, CKEditor 4. See [Adding Media](../adding-media/) for updated instructions.
+{{< /alert >}}
+
 ### NOTE TO USERS OF YMCA Website Services 2.4+
 
 > This documentation is not up-to-date if you are using [YMCA Website Services 2.4](https://community.openymca.org/t/version-2-4-released-q1-2020-major-release/624) and later.

content/en/docs/user-documentation/text-editor/adding-links/_index.md

@@ -0,0 +1,50 @@
+---
+title: 'Adding Links'
+weight: 1
+---
+
+{{< youtube id=-AJLwiKC3oE >}}
+
+-----
+
+Links are simple in YMCA Website Services - just highlight your text and click the link icon (`🔗`) or type <kbd>Ctrl</kbd> / <kbd>Cmd</kbd> + <kbd>K</kbd>. Once the pop-up appears, type your URL into the field and click **Save**.
+
+*[Read more and demo this on CKEditor Site.](https://ckeditor.com/docs/ckeditor5/latest/features/link.html)*
+
+{{< tabpane text=true >}}
+{{% tab header="CKEditor 5" lang="cke5" %}}
+![The link button in the CKEditor 5 toolbar.](adding-links--cke5-toolbar.png "The link button in the CKEditor 5 toolbar.")
+![The link popup in CKEditor 5.](adding-links--cke5-popup.png "The link popup in CKEditor 5.")
+{{% /tab %}}
+{{% tab header="CKEditor 4" lang="cke4" %}}
+![The link button in the CKEditor 4 toolbar.](adding-links--cke4-toolbar.png "The link button in the CKEditor 4 toolbar.")
+![The link popup in CKEditor 4.](adding-links--cke4-popup.png "The link popup in CKEditor 4.")
+{{% /tab %}}
+{{< /tabpane >}}
+
+<hr />
+
+## Advanced options
+
+In the Advanced options of the link dialog, you can add attributes to links, including a label, HTML ID, and CSS classes. You can also opt to have your link open in a new window/tab.
+
+{{< tabpane text=true >}}
+{{% tab header="CKEditor 5" lang="cke5" %}}
+![The advanced link options in CKEditor 5.](adding-links--cke5-advanced.png "The advanced link options in CKEditor 5.")
+{{% /tab %}}
+{{% tab header="CKEditor 4" lang="cke4" %}}
+![The advanced link options in CKEditor 4.](adding-links--cke4-advanced.png "The advanced link options in  CKEditor 4.")
+{{% /tab %}}
+{{< /tabpane >}}
+
+## Linking tips
+
+* For links on your website, don’t use the full URL. Delete everything beginning with the `/` after your `.com`, `.org`, etc.
+  * For example, for ymca.org/about, you would choose /about. This is called the relative path, and it will help your analytics tracking.
+* For links on other websites, grab the full URL, including the `https://`.
+  * For example, for example.org/about, you would choose https://example.org/about.
+* For email links, add `"mailto:example@exampleymca.org."`
+
+To update/change a link, click on the link text then click the link icon or use the popup options (in CKEditor 5).
+
+To remove a link, highlight the link text and click the unlink icon.

content/en/docs/user-documentation/text-editor/adding-media/_index.md

@@ -0,0 +1,61 @@
+---
+title: Adding Media with CKEditor 5
+description: Using the new unified Media editor.
+weight: 1
+---
+
+Once your site is updated to use CKEditor 5 you will see a new **Insert Media** button that unifies the processes for embedding Images, Documents, and Videos. ![The new Insert Media button in CKEditor 5.](adding-media--button.png)
+
+## Add or select media
+
+1. To get started, click **Insert Media** in the CKEditor toolbar (or try the <abbr title="Show more items"><kbd> ⋮ </kbd></abbr> button if it's hidden). You will be presented with the **Add or select media** dialog. ![The "Add or select media" dialog](adding-media--dialog.png)
+2. Choose the media type (Image, Document, etc.) that you would like to embed from the list on the left. 
+3. Add or upload your media:
+    - If you are adding new media:
+      - If given the option, drag and drop the item from your filesystem to the dialog, or click **Select File**.
+      - For Video (via YouTube or Vimeo), add the video directly via **Admin** > **Content** > **Media** **Add Media** > **Video** before opening the dialog.
+    - If you are reusing media that exists on the site, scroll down and search for the item, then click the checkbox to select it.
+4. Choose **Insert selected** to embed the chosen media.
+
+## Customizing your media
+
+Once your media has been inserted into the field, you can hover over the media to choose from a variety of options.
+
+![The embedded media options with labels for "Toggle caption on", "Link media", "Add alt text", "Choose view mode", and "Set alignment"](adding-media--options.png)
+
+### Toggle caption on
+
+Displays a **Caption** area below your image. Once toggled, type your caption below the image.
+
+### Link media
+
+Allows the media to be linked. See [Adding Links](../adding-links) for more information.
+
+### Override media image alternative text
+
+_(for Images only)_
+
+Allows you to add alternative text to the media. See [WebAIM's guidelines on Alternative Text](https://webaim.org/techniques/alttext/) for help choosing the right alt text for your image.
+
+### View mode
+
+Allows you to select the size of the image. Typically you might choose "Full", "Half", or "Thumbnail". Options may vary depending on site configuration.
+
+### Alignment
+
+Choose how to align the media:
+
+- Break text
+- Align left and wrap text
+- Align center and break text
+- Align right and wrap text
+
+### Moving your media
+
+Click and drag anywhere on the inserted media to relocate it in the WYSIWYG area.
+
+Use the <kbd>⮐</kbd> button at the top or bottom of the media to insert a paragraph before or after it.
+
+### Deleting your media
+
+Click to select the media, then type <kbd>Delete</kbd> to remove it.

content/en/docs/user-documentation/text-editor/basic-text-formatting/_index.md

@@ -0,0 +1,66 @@
+---
+title: 'Basic Text Formatting'
+weight: 1
+---
+
+{{< youtube id=bmqFQYLAa1c >}}
+
+-----
+
+Choose any of the options for your text below by clicking on the icon/performing the keyboard shortcut indicated. To format text you’ve previously typed, highlight the text and then click on the button in the editor. Many formatting options also have [keyboard shortcuts](https://ckeditor.com/docs/ckeditor5/latest/features/keyboard-support.html).
+
+## CKEditor 5 Toolbar
+
+![The CKEditor 5 toolbar.](basics--cke5-toolbar.png)
+
+[Demo Basic Text Formatting on CKEditor 5.](https://ckeditor.com/ckeditor-5/demo/feature-rich/) or read [more detail about these features](https://ckeditor.com/docs/ckeditor5/latest/features/index.html#ckeditor-5-wysiwyg-editor-features-and-functions).
+
+1. **Bold**
+2. _Italics_
+3. <u>Underline</u>
+4. <strike>Strikethrough</strike>
+5. **Text alignment** - Choose from Align left, Align center, Align right, or Justify.
+6. **Font color** - Use sparingly to avoid reduced text accessibility.
+7. **Font background color** - Use sparingly to avoid reduced text accessibility.
+8. **Decrease indent** - Only available when editing a list or block.
+9. **Increase indent** - Only available when editing a list or block.
+10. **Heading** - Set paragraphs or heading levels—headings in your content [should be ordered sequentially](https://www.a11yproject.com/posts/how-to-accessible-heading-structure/) for the best accessibility.
+11. **Link** - See [Adding links](../adding-links).
+12. **Bulleted list**
+    - Lists
+    - like
+    - this.
+13. **Numbered list**
+    1. Lists
+    2. like
+    3. this.
+14. **Block quote**
+15. **Insert media** - See [Adding media](../adding-media).
+16. **Show more items** - This will appear at the end of the first row of buttons and allow you to view the rest of the editor buttons.
+17. **Remove format** - Clears all formatting. Useful when pasting content from Word or other applications.
+18. **Insert table** - A [feature-rich table editor](https://ckeditor.com/docs/ckeditor5/latest/features/tables/tables.html).
+19. **Source** - View or edit the source code of the content. Be aware that some HTML tags may be stripped out due to Drupal's Text Format rules. Click **About text formats** below the editor to learn more.
+20. **Special characters** - Insert mathematical operators, currency symbols, punctuation, or graphic symbols not typically accessible from the keyboard.
+21. **Language** - Mark specific sections of the content as different languages so that browsers and screen readers can correctly interpret them. [More info.](https://ckeditor.com/docs/ckeditor5/latest/features/language.html)
+
+## CKEditor 4 toolbar
+
+![The CKEditor 4 toolbar.](basics--cke4-toolbar.png)
+
+[Demo Basic Text Formatting on CKEditor 4 >](https://ckeditor.com/ckeditor-4/demo/#article)
+
+1. **Bold Text** - Ctrl+B (Windows) or Command(⌘)+B (Mac) or clicking/unclicking the B icon
+2. **Italics -** Ctrl+I (Windows) or Command(⌘)+I (Mac) or clicking/unclicking the I icon
+3. **Underline -** Ctrl+U (Windows) or Command(⌘)+U (Mac)or clicking/unclicking the U icon
+4. **Strikethrough -** Clicking/unclicking the S icon
+5. **Alignment controls -** Left, Center, Right, and Justify.
+6. **Font Color -** A small grid of swatches you can apply to your text. Overrides the default font-color
+7. **Text Background color** (not recommended)
+8. **Font** (should remain Cachet or Verdana to conform to YMCA brand standards)
+9. **Font Size -** A dropdown to select the size of your text. Measured in points, not pixels. Overrides the default font size for your text, including styles and format.
+10. **Indent -** Add one or more indents to your copy. Also, have the option to undo the indent.
+11. **Format -** A dropdown list of text formats you can apply to your content. Helps to create sections. Comes out-of-the-box with six heading formats.
+
+> Most Ys will not use the “Formatted” format, which styles text like HTML code.
+
+12. **Bulleted/Numbered lists -** Click the numbered or bulleted list icon to create a list. You can create indented bullets by hitting your tab key or clicking on the indent icon