docs: use shorter and more straighforward expressions

README.md

@@ -1,132 +1,147 @@
 # Extended Markdown Syntax - Obsidian Plugin
 
-Provides some alternatives for inline formatting using non-standard syntaxes instead of using html tags, such as underline, superscript, and much more.
+![banner.png](docs/assets/banner.png)
 
-You can easily create text that is <ins>underlined</ins>, <sup>superscripted</sup>, or <sub>subscripted</sub> without any pain of writing html tags. And don't forget, this plugin supports both modes: editor mode and preview mode.
+Provides some alternatives for inline and block formatting using non-standard syntaxes instead of using html tags, such as underline, superscript, and much more.
 
-![formattings.gif](docs/media/formattings.gif)
+## 🚀 Main Features
 
-## Features
+- Extended inline syntax, including:
-
-- Extends your Markdown with some inline syntax which aren't available in the native Obsidian syntax, including:
     - insertion (underline),
     - Discord-flavored spoiler,
     - Pandoc-style superscript and subscript,
     - custom color tag for highlight, and
     - custom span with ability to insert your own class(es).
-- _Modified_ Pandoc-style fenced div syntax for customizing block-level format.
+- _Modified_ Pandoc-style fenced div for block-level syntax.
-- Uses non-prerendered Markdown preview when formatting such syntax in live-preview mode, gives a more intuitive impression in such a way.
+- Edit formatted text directly without omitting its style, in contrast to using HTML tags.
-- Be aware of inline and block context, so syntax won't be parsed while it encounters such a codeblock, codespan, or context boundary.
+- Context-aware, syntax won't be parsed while it encounters such a codeblock, codespan, or context boundary.
 - Quick format with commands and context menu.
-- Has an ability to customize the color of the highlight with your own desire through settings.
+- Toggle specific syntax on and off.
-- Provides color menu for highlight, improves more efficient way to change the color.
+- Customize your own color tags for custom highlight.
-- Provides tag menu for custom span and fenced div.
+- Predefine your own tags for custom span and fenced div.
-- Toggling specific syntax on and off through the settings.
+- Supports rendering exported PDF.
-- Configurable tag display behaviour for the tag of the highlight, custom span, and fenced div.
-- Supports parsing exported PDF (can be switched off in the settings).
 
-## Usage
+## ✍️ Usage
 
 ### 1. Inline Formatting
 
-There is four formatting types that currently developed in this plugin: **insertion** (underline), **Discord-flavoured spoiler**, **Pandoc-flavoured superscript and subscript**, custom tag for ==highlight==, and custom span that can be inserted with your own class(es).
+There are six inline formattings that currently developed in this plugin:
 
 | Type        | Syntax                 | Result                                                        |
 | ----------- | ---------------------- | ------------------------------------------------------------- |
 | insertion   | `++your text++`        | <ins>your text</ins>                                          |
-| spoiler     | `\|\|your text\|\|`    | <span style="background: #2e2e2e">your text</span>          |
+| spoiler     | `\|\|your text\|\|`    | <span style="background:#2e2e2e">your text</span>             |
 | superscript | `^your-text^`          | <sup>your-text</sup>                                          |
 | subscript   | `~your-text~`          | <sub>your-text</sub>                                          |
 | highlight   | `=={color}your text==` | <mark>your text</mark>                                        |
 | custom span | `!!{myCls}your text!!` | your text (should be rendered with the `myCls` class defined) |
 
-By default, **insertion** give the text underline style, **spoiler** hide the text and can be revealed by clicking it (or hovering over it in editor mode), while **superscript** and **subscript** make the text being raised or lowered as `<sup>` and `<sub>` do.
+By default:
+- **insertion** give the text underline style,
+- **spoiler** hide the text and can be revealed by clicking it (or hovering over it in editor mode),
+- **superscript** and **subscript** make the text being raised or lowered as `<sup>` and `<sub>` do.
 
-The main advantage of using those syntaxes over html tags is that those syntaxes are rendered properly in the editor alongside other built-in syntaxes. So you can combine them without blocking other style being rendered in editor, in stark contrast to the html tags, for instance `this *is ++italic-underlined text++*`.
+Additionally, for the **highlight** and **custom span**, you may insert a tag right after the opening delimiter, specifying the color for the highlight, and the classes for the custom span.
-
-To give those formats, you can wrap the text with specific delimiters, covering it on both sides (see the table above). Additionally, for the highlight and custom span, you may insert a tag right after the opening delimiter, specifying the color for the highlight, and the classes for the custom span.
-
-For ease access, in the editor, the color button will appear after the opening delimiter when the cursor or selection touches the highlight. Clicking on it shows colors menu and let us choose the desired color (you can disable the color botton in settings, and thus will be hidden in the editor).
-
-> [!Note]
->
-> You can use typing-helper plugins such as [Easy Typing](https://github.com/Yaozhuwa/easy-typing-obsidian) to make formatting faster and efficient.
 
 ### 2. Block Formatting
 
-Currenty, this plugin only support one type of block syntax, that's Pandoc-style fenced div (with some modifications).
+Currenty, this plugin only support **Pandoc-style fenced div** with some modifications. You only need an opening delimiter (three consecutive colons at least) to start the syntax. Blank line or the end of the document will act as a syntax closing. No need of closing delimiter.
 
 ```markdown
 ::: my-class-1 my-class-2
 This is fenced div content.
+
+::: another-class
+Another fenced div content.
 ```
 
-But it has been modified in this plugin to become a way more restricted, avoiding conflict with the built-in syntax. So, you will only need an opening delimiter to start this format in the concerned text (closing delimiter isn't needed). Optionally, you can insert a tag containing your own classes, which then can be styled through the CSS snippet.
+### 3. Customizable Highlight
 
-For example:
+Under "Custom highlight" section in the settings, you can:
 
-```css
+- **show the color button**, providing color menu when you click on it,
-/* Your CSS snippet */
+- **adjust opacity** of the highlight,
-.align-center {
+- **customize color palettes** based on its tag:
-    text-align: center;
+    - first field for its name displayed in the color menu,
-}
+    - second field for its tag inserted into the highlight syntax,
+    - show or hide each palette from the color menu,
+    - rearrange colors by dragging 6-dots icon on the left side.
 
-.medium-size {
+<details>
-    font-size: 24px;
+<img src="docs/assets/custom-highlight.gif" alt="custom-highlight.gif"/>
-}
+</details>
 
-.monospace {
+### 4. Predefined Tags
-    font-family: monospace;
-}
-```
 
-You can apply those rules above like this.
+In the settings, you can predefine specific tags for **custom span** and **fenced div**, then can be displayed in the tag menu. Same as the color palattes, you can set their name and arrange them.
 
-```markdown
+### 5. Commands and Context Menu
-::: align-center medium-size monospace
+
-Center-aligned text
+This plugin provides commands to toggle each formatting type, also commands to show the color and tag menu. You can set the keymap for each of them through "Hotkeys" in the settings.
-with medium font size and monospace style.
+
-```
+It also brings functionality of all those commands (except for fenced div) to the context menu, by right-clicking on the editor and choosing "More format".
+
+<details>
+<img src="docs/assets/commands.gif" alt="commands.gif"/>
+</details>
 
 > [!Note]
 >
-> Custom align no longer available in this plugin, because it is already covered by the fenced div.
+> In mobile devices, those commands can be added into the toolbar.
 
-### 3. Commands and Context Menu
+### 6. Tidier Formatting
 
-This plugin provides commands to toggle each formatting type on and off, also commands to show the color and tag menu for each of highlight, custom span, and fenced div. You can set the keymap for each of them through "Hotkeys" in the settings.
+With "Tidier formatting" enabled in the settings, you can format a single word simply by placing the cursor on it, without the need to select the entire word. Otherwise, it acts like a normal wrapper.
 
-This plugin also adds functionality of all those commands (except for fenced div) to the context menu, by right-clicking on the editor and choosing "More format" (below "Insert" in the formatting section).
+<details>
-
+<img src="docs/assets/tidier-formatting.gif" alt="tidier-formatting.gif"/>
-Mimicking how Obsidian formats the text, this plugin brings an ability to do "tidier" formatting. That means that the plugin will try to format the whole word that touches the cursor. So, you don't need to select all over the word. But, if you still want the formatting to behave like normal auto-wrap, you toggle off "Tidier formatting" in the settings.
+</details>
-
-### 4. Tweaking the Settings
-
-Because some syntax may not be required, or just simply you don't want to use it, this plugin provides ability to turn specific syntax off under the "Syntax switch" section. Also, this plugin give some option to turn those off only in one mode (either editor or preview mode), gives you more freely and flexible choice depend on your needs.
-
-Moreover, the tag display behaviour of the highlight, custom span, and fenced div can be configured through the "Tag display behaviour" section. If you don't want the tag to be hidden, you can set it to "Always visible" in the live-preview mode, or toggle it on in the preview mode.
-
-This plugin provides a way for tweaking the highlight, without exhaustingly bring the CSS snippet into it. In the "Custom highlight" section, you can adjust:
-- visibilty of the color button,
-- the opacity of the highlight color for each light mode and dark mode, range from 0 to 1 (zero means that the highlight will be fully transparent),
-- the list of the color palattes, by adding the new one, changing their color and their tag string, or deleting them,
-- also, it is equipped with ability to change the name, arrange, and decide the colors to be displayed in the color menu.
-
-Along with the latest version, you can add some predefined tags to the custom span and fenced div (under the "Custom span" and "Fenced div" sections), so those will be displayed in the tag menu. These features behave like the color palattes in the "Custom highlight", except you have to manually set the style rules within the CSS snippet manually if you want to give each tag some styles.
-
-For the last section, the "Others" section, you can choose:
-- whether the delimiter can be escaped by backslash or not (editor only), and
-- whether the syntax will be parsed in the exported PDF or not.
 
 > [!Note]
 > 
 > You don't need to reload the app after changing the settings.
 
-## Syntax Rules
+### 7. Other Tweaks
+
+- Enable/disable each formatting type individually under "Syntax switch" section.
+- Prevent fenced div from being styled in source mode.
+- Specifies when tags should be displayed under "Tag display behavior" section.
+- etc...
+
+## 🎨 Styling Custom Spans and Fenced Divs
+
+With tag attached to them, you can insert your own CSS style rules based on their tag. For instance, you can apply this CSS rules to the markdown below:
+
+```css
+.text-large { font-size: 48px }
+.text-green { color: green }
+
+.align-center { text-align: center }
+.bordered { border: 4px solid red }
+```
+
+```markdown
+!!{text-large text-green}Large text with green color.!!
+
+:::align-center bordered
+Should be aligned to the center
+and bordered.
+```
+
+<details>
+<summary>Expected result:</summary>
+<img src="docs/assets/tag-styling.png" alt="tag-styling.png"/>
+</details>
+
+> [!Note]
+>
+> For which characters are allowed in the tag, see "Syntax Rules" section below.
+
+## 📜 Syntax Rules
 
 We move the explanation to [this page](./docs/rule.md).
 
-## Installation
+## 📦 Installation
 
 - In-app
     - Open settings.
@@ -139,9 +154,14 @@ We move the explanation to [this page](./docs/rule.md).
     - Create a folder named `extended-markdown-parser` under `YOUR_VAULT_NAME/.obsidian/plugins`.
     - Place `manifest.json`, `main.js`, and `style.css` from the latest release into the folder.
     - Enable it through the "Community plugin" setting tab.
-- Using [BRAT](https://github.com/TfTHacker/obsidian42-brat).
+- Using [BRAT](https://github.com/TfTHacker/obsidian42-brat)
+    - Install and enable "BRAT" plugin in "Community plugins" list.
+    - Choose "BRAT" setting tab.
+    - Click "Add beta plugin" under "Beta plugin list" section.
+    - Enter this repo link into "Repository" input field.
+    - Check "Enable after installing the plugin" and click "Add Plugin".
 
-## FAQ's
+## ❓ FAQ's
 
 ### Is it working on the table and callout?
 Of course it's working on both, except for the fenced div.
@@ -152,7 +172,7 @@ I tested it on a 250kB file and it's still working fine. This plugin also uses p
 ### Will it cause conflict with other plugins that concerns extending syntax?
 It depends on what character the others use in their syntax.
 
-## Roadmap
+## 📋 Roadmap
 
 - [x] Enable/disable formatting in settings
 - [x] Applicable on mobile
@@ -163,18 +183,18 @@ It depends on what character the others use in their syntax.
 - [x] ~~Class suggester~~ Predefined tags for custom span and fenced div
 - [ ] ~~More syntax, if necessary~~ *I'll be over here for a while*
 
-## Compatibility Note
+## ⚙️ Compatibility Note
 
 This plugin have been tested in the latest version of Obsidian (about 1.7.x - 1.8.x), and haven't been tested yet in the version 1.6.x and below.
 
-## Known Issues
+## 🐞 Known Issues
 
 - Delimiter escaping doesn't work in the preview mode.
 - Cannot escape spoilers that are inside table cells (in source mode). (**cannot be fixed**)
 
 Feel free to let me know if you find any bugs...
 
-## Credit
+## 🙏 Acknowledgment
 
 Thanks to:
 - [Pandoc](https://pandoc.org/MANUAL.html) for the idea of some syntax,