Skip to content

Commit c3029db

Browse files
kotaindah55kotaindah55
committed
docs: add latest features explanation
1 parent 3bcb491 commit c3029db

File tree

1 file changed

+51
-159
lines changed

1 file changed

+51
-159
lines changed

‎README.md‎

Lines changed: 51 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,13 @@ You can easily create text that is <ins>underlined</ins>, <sup>superscripted</su
1414
- Pandoc-style superscript and subscript,
1515
- custom color tag for highlight, and
1616
- custom span with ability to insert your own class(es).
17-
- Pandoc-style fenced div syntax for customizing block-level format.
17+
- _Modified_ Pandoc-style fenced div syntax for customizing block-level format.
1818
- Uses non-prerendered Markdown preview when formatting such syntax in live-preview mode, gives a more intuitive impression in such a way.
1919
- Be aware of inline and block context, so syntax won't be parsed while it encounters such a codeblock, codespan, or context boundary.
20+
- Quick format with commands and context menu.
2021
- Has an ability to customize the color of the highlight with your own desire through settings.
2122
- Provides color menu for highlight, improves more efficient way to change the color.
22-
- Set your own custom class(es) for custom span and fenced div syntax.
23+
- Provides tag menu for custom span and fenced div.
2324
- Toggling specific syntax on and off through the settings.
2425
- Configurable tag display behaviour for the tag of the highlight, custom span, and fenced div.
2526
- Supports parsing exported PDF (can be switched off in the settings).
@@ -33,7 +34,7 @@ There is four formatting types that currently developed in this plugin: **insert
3334
| Type | Syntax | Result |
3435
| ----------- | ---------------------- | ------------------------------------------------------------- |
3536
| insertion | `++your text++` | <ins>your text</ins> |
36-
| spoiler | `\|\|your text\|\|` | <span style="background: #2e2e2e">your text</span> |
37+
| spoiler | `\|\|your text\|\|` | <span style="background: #2e2e2e">your text</span> |
3738
| superscript | `^your-text^` | <sup>your-text</sup> |
3839
| subscript | `~your-text~` | <sub>your-text</sub> |
3940
| highlight | `=={color}your text==` | <mark>your text</mark> |
@@ -53,29 +54,65 @@ For ease access, in the editor, the color button will appear after the opening d
5354
5455
### 2. Block Formatting
5556

56-
Currenty, this plugin only support one type of block syntax, that's Pandoc-style fenced div.
57+
Currenty, this plugin only support one type of block syntax, that's Pandoc-style fenced div (with some modifications).
5758

5859
```markdown
5960
::: my-class-1 my-class-2
6061
This is fenced div content.
6162
```
6263

63-
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. Optionally, you can insert a tag containing your own classes, which then can be styled through the CSS snippet.
64+
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.
65+
66+
For example:
67+
68+
```css
69+
/* Your CSS snippet */
70+
.align-center {
71+
text-align: center;
72+
}
73+
74+
.medium-size {
75+
font-size: 24px;
76+
}
77+
78+
.monospace {
79+
font-family: monospace;
80+
}
81+
```
82+
83+
You can apply those rules above like this.
84+
85+
```markdown
86+
::: align-center medium-size monospace
87+
Center-aligned text
88+
with medium font size and monospace style.
89+
```
6490

6591
> [!Note]
6692
>
6793
> Custom align no longer available in this plugin, because it is already covered by the fenced div.
6894
69-
### 3. Altering the Settings
95+
### 3. Commands and Context Menu
96+
97+
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.
98+
99+
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).
100+
101+
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.
70102

71-
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. 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.
103+
### 4. Tweaking the Settings
104+
105+
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.
72106

73107
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.
74108

75-
Along with the latest version, this plugin provides a way for tweaking the custom highlight, without exhaustingly bring the CSS snippet into it. In the "Customize highlight" section, you can adjust:
109+
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:
76110
- visibilty of the color button,
77111
- 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),
78-
- the list of the custom colors, 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.
112+
- the list of the color palattes, by adding the new one, changing their color and their tag string, or deleting them,
113+
- also, it is equipped with ability to change the name, arrange, and decide the colors to be displayed in the color menu.
114+
115+
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.
79116

80117
For the last section, the "Others" section, you can choose:
81118
- whether the delimiter can be escaped by backslash or not (editor only), and
@@ -87,149 +124,7 @@ For the last section, the "Others" section, you can choose:
87124
88125
## Syntax Rules
89126

90-
To make clear and avoid ambiguity, some rules are applied to the syntax.
91-
92-
#### 1. General Rules for All Syntax
93-
94-
- Any built-in syntax from Obsidian has a higher precedence than that in this plugin.
95-
96-
#### 2. General Rules for Inline Syntax (Insertion, Spoiler, Superscript, Subscript, Highlight Color Tag, Custom Span)
97-
98-
- Opening delimiter must not be followed by any whitespace character (regular space, tab, and new line), and the closing one must not be preceded by any whitespace character.
99-
- Delimiter must satisfy its requiered length as will be explained later, and must not be preceded or followed by the same character as the delimiter, or the same non-escaped if configured for that.
100-
- (Editor only, can be altered through the settings) Delimiter must not be escaped, if it was configured to not be escaped, by a backslash. Otherwise, it will act as literal character.
101-
- Formatting only occurs when opening delimiter met its closing (doesn't include highlight).
102-
- Content text, that is surrounded by delimiters, must at least one character.
103-
- Content text must not have two or more new line character.
104-
105-
For better understanding, the table below can give some example applying those rules:
106-
107-
| Valid | Invalid |
108-
| -------------------------------------------------- | ------------------------------------------ |
109-
| `++lorem++` | `++ lorem++` `++lorem` `lorem++` |
110-
| `++lor em++` | `++lorem ++` |
111-
| `++l++` | `++++` |
112-
| `++l+o+r+em++` | `++dfdf+++` |
113-
| `++lo++rem++` (third plus pair doesn't include) | `++lo\nre\nm++` (`\n` as a new line char) |
114-
| `++lo\nr e m++` | `+++lore++m+++` |
115-
| `++ lor++em++` (first one doesn't include) | `++ ++` |
116-
| `\+++lorem++ ++ipsum\+++` (if escaping is enabled) | `\++lorem++ +\++ipsum\++++` |
117-
118-
#### 3. Rules for Insertion and Spoiler
119-
120-
- Insertion is defined as text consist at least one character surrounded by exactly double plus signs (`++`) on each side.
121-
- Spoiler is the same as the insertion, it's just surrounded by exactly double bars (`||`) on each side.
122-
123-
| Valid format | Invalid format |
124-
| ---------------------------------------- | ------------------------------------------------------------------ |
125-
| `++ins++` `++ins also++` | `++ not ins++`, `++not ins` `++not ins ++` `+++not ins++` |
126-
| `\|\|spoiler\|\|` `\|\|spoiler also\|\|` | `\|\| not spoiler\|\|`, `\|\|not spoiler \|\|` `\|\|not spoiler\|` |
127-
128-
#### 4. Rules for Superscript and Subscript
129-
130-
- Superscript is defined as text consist at least one character surrounded by only single caret (`^`) on each side, and must not contain any of whitespace character.
131-
- Subscript act like superscript, it's just use single tilde as delimiter.
132-
- Thus, insertion and spoiler allow its content to have any whitespace character. It's contasts with the case of superscript and subscript.
133-
134-
| Valid format | Invalid format |
135-
| -------------------- | --------------------------------------------------------------- |
136-
| `^sup^` `^sup-also^` | `^ not-sup^`, `^not sup^`, `^not-sup` `^not-sup ^` `^^not-sup^` |
137-
| `~sub~` `~sub-also~` | `~ not-sub~`, `~not sub~`, `~not-sub` `~not-sub ~` `~not-sub~~` |
138-
139-
#### 5. Rules for Custom Span
140-
141-
- Custom span use the same rules as insertion and spoiler, except it uses double exclamation marks on each side to wrap its content.
142-
- It also comes with a tag you can insert a class or classes into. The tag consists alphanumeric character(s), hyphen(s), and space(s) (at least one character), wrapped by curly brackets on each side. A space is treated as a devider between classes. Other character inserted before or within the tag will disable it, so it will be stated as invalid tag.
143-
144-
| Valid tag | Invalid tag |
145-
| ------------------------- | ----------------------------------------------------------- |
146-
| `!!{my-class}span!!` | `!! {class}not span!!`, `!!a{class}span!!` |
147-
| `!!{class-1 cls-2}span!!` | `!!{}span!!,` `!!{*_}not span !!`, `!!{green_color}span!!` |
148-
149-
Later on, you can add corresponding class in your CSS snippet. For instance, if you type `!!{my-class strong-text}My text!!`, it will be rendered in HTML as `<span class="my-class strong-text">My text</span>` (with additional `cm-custom-span` class in the editor, and `custom-span` in the preview).
150-
151-
#### 6. Rules for Highlight Color Tag
152-
153-
The color of each highlight can be customized by adding color tag exactly after its opening delimiter. The tag behaves like the custom span tag, except it doesn't allow any space within it.
154-
155-
| Valid color tag | Invalid color tag |
156-
| -------------------------- | --------------------------------------------------------------------- |
157-
| `=={color}highlight==` | `== {color}highlight==`, `==a{color}highlight==` |
158-
| `=={abcAb--10}highlight==` | `=={ }highlight==,` `=={*_}highlight==`, `=={green_color}highlight==` |
159-
160-
Valid color tag will be added in the highlight classes, so `=={red}Red==` will be parsed in html tag as **`<span class="cm-custom-highlight cm-custom-highlight-red">`** in editor and **`<mark class="custom-highlight custom-highlight-red">`** in preview mode.
161-
162-
#### 7. NOTE: Delimiter Escaping
163-
164-
As already explained, using escaper backslash can change the semantic meaning to that being escaped. Escaped punctuation is treated as regular character that doesn't have functional use. This applies to those delimiters when "Delimiter escaping" option is switched on.
165-
166-
```
167-
++insertion++ \++not insertion\++ in editor mode
168-
```
169-
170-
However, we can only apply this feature in editor mode, since escaped character being rendered as normal character without being wrapped by any tag (and it makes sense).
171-
172-
```
173-
++insertion++ \++still insertion\++ \+\+still insertion\+\+, \+++not insertion+\++ in preview mode
174-
```
175-
176-
Due to this condition, "Delimiter escaping" was turned of by default to maintain consistency between editor and preview mode.
177-
178-
#### 8. Pandoc-style Fenced Div
179-
180-
Since the align tag has been removed, as it is not as flexible as though, I decided to bring the plugin with Pandoc-style fenced div, which more flexible and intuitive for block customizing. Even though it is Pandoc-style, the implemented rule in this plugin is more restricted to avoid unnecessary broken layout and conflicts (or even worse).
181-
182-
- Fenced div must be opened by a line consists of three or more colons (`:::`), at must be located exactly in the line start.
183-
- The colons may, and only, be followed by tag that consists of alphanumeric, hyphen, and space (can be empty).
184-
- Other characters aren't allowed in the opening line. Even a colon that was inserted in the tag range will make the format invalid.
185-
- It is only be closed by different context (e.g. list, blockquote), blank line, or the end of the document.
186-
- You don't need to close the format with any delimiter.
187-
188-
```
189-
:::
190-
valid fenced div
191-
192-
::: my-class
193-
also valid
194-
195-
:::my-class other-class
196-
also
197-
valid
198-
```
199-
200-
#### 9. Context-aware Formatting
201-
202-
Any syntax that are written in the codespan, codeblock, math, comment, and wikilink don't apply the rules, so they are treated according to their context. Or, in the nutshell, they aren't formatted. This corresponds to the many of markdown implementation, as well as that implemented in Obsidian.
203-
204-
In addition in the editor, any formatting above doesn't overlapping its block context. So if a opening delimiter, i.e. double plus signs for insertion, was found in heading, and didn't meet any double plus signs but in the next line (which is paragraph for instance), then the second delimiter isn't treated as a closing for that opening.
205-
206-
Example below can give some better understanding:
207-
208-
Markdown:
209-
> ```
210-
> # Heading ++1
211-
> The paragraph.++
212-
>
213-
> Another ++paragraph
214-
> > Blockquote++
215-
>
216-
> 1. ++List
217-
> 2. another list++
218-
> 3. another ++list
219-
> lazy continuation++
220-
> ```
221-
222-
Expected result:
223-
> <h1>Heading ++1</h1>
224-
> The paragraph.++
225-
>
226-
> Another ++paragraph
227-
> <blockquote>Blockquote++</blockquote>
228-
>
229-
> <ol><li>++List</li>
230-
> <li>another list++</li>
231-
> <li>another <ins>list
232-
> <br>lazy continuation</ins></li></ol>
127+
We move the explanation to [this page](./docs/rule.md).
233128

234129
## Installation
235130

@@ -241,13 +136,11 @@ Expected result:
241136
- Type "Extended Markdown Syntax" in the search box.
242137
- Install and enable it.
243138
- Manual
244-
- Create a folder named `extended-markdown-parser` under `.obsidian/plugins`.
139+
- Create a folder named `extended-markdown-parser` under `YOUR_VAULT_NAME/.obsidian/plugins`.
245140
- Place `manifest.json`, `main.js`, and `style.css` from the latest release into the folder.
246141
- Enable it through the "Community plugin" setting tab.
247142
- Using [BRAT](https://github.com/TfTHacker/obsidian42-brat).
248143

249-
---
250-
251144
## FAQ's
252145

253146
### Is it working on the table and callout?
@@ -259,15 +152,15 @@ I tested it on a 250kB file and it's still working fine. This plugin also uses p
259152
### Will it cause conflict with other plugins that concerns extending syntax?
260153
It depends on what character the others use in their syntax.
261154

262-
## Features to be Implemented in The Future
155+
## Roadmap
263156

264157
- [x] Enable/disable formatting in settings
265158
- [x] Applicable on mobile
266159
- [x] ~~Fixing paragraph alignment bug~~ For now, use fenced div to customize block level format
267160
- [x] Customize highlighting colors
268161
- [ ] Customize formatting styles
269-
- [ ] Applying syntax quickly using shortcuts and context menu
270-
- [ ] Class suggester for custom span and fenced div
162+
- [x] Applying syntax quickly using shortcuts and context menu
163+
- [x] ~~Class suggester~~ Predefined tags for custom span and fenced div
271164
- [ ] ~~More syntax, if necessary~~ *I'll be over here for a while*
272165

273166
## Compatibility Note
@@ -278,7 +171,6 @@ This plugin have been tested in the latest version of Obsidian (about 1.7.x - 1.
278171

279172
- Delimiter escaping doesn't work in the preview mode.
280173
- Cannot escape spoilers that are inside table cells (in source mode). (**cannot be fixed**)
281-
- ~~Sometimes, faster scrolling on a big file (by using scroll bar thumbs and moving it suddenly to the bottom) breaks the customized highlight color. (*can be fixed temporarily by scrolling with fair speed through the highlight*)~~ _Already fixed_
282174

283175
Feel free to let me know if you find any bugs...
284176

0 commit comments

Comments
 (0)