Introduce a new docsify config for markdown enrichment

Koooooo-7 commented 3 months ago

Feature request

Currently, the docsify config is sticky to each special key rules and losses match via regex and there is no a config block to distinguish the docsify config part nor the markdown attrs, which is hard to maintained. It doesn't support multi value groups also, and can not extend new functions with flexibilities. So we proposal to introduce a new config system of docsify regarding attributes and multiple values.

Problem or desire

Such as the class configs, it only allows to specific the single class instead of a value group.

Proposal

For the values group supporting and easy to parse the configs. There has two possible solution.

Colon Style [Text](page.md ':[foo target=_blank class=bar baz] This is the title')
Bracket Style [Text](page.md '{{ foo: true, target: _blank, class: bar baz }} This is the title')

For the unified configs, there may have some breaking change for current config, need to resort current behaviors first.

Current possible configs:

Single Key ':ignore title'
Single Key value ':type=code' ':size=widthXheight'
Single Key value with multi following key value. ':type=iframe width=100% height=400px'.
Single Key value not in a quoto block # Heading1 :id=customId

more details see #2472

Implementation

For the both suitable and comfortable for docsify and users. Temperately，we prefer to the single Bracket Style rules. and we also support the both configs rules （< v5 and v5+） in v5 also.

By default, we will handle the two configs in docsify itself. and also consider introduce a userNewConfig = true/false (default ture) option for the manually disable in some reason.

NOTE: both the useNewConfig option and the config rules (< v5) will be removed in v6.

paulhibbitts commented 3 months ago

Hi @Koooooo-7 , thanks for creating this issue for tracking! I thought I would try to add an example of the proposed bracket style to the existing Docs to see how it fits in, reads, etc, and here are examples of the two formats:

Class names

![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass')

Multiple classes can be applied to an image by the use of double curly brackets, for example

![logo](https://docsify.js.org/_media/icon.svg '{{ class: aCssClass anotherCssClass }}')

or...

Class names

![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass')

Multiple classes can be applied to an image by the use of a colon followed by a second set of square brackets, for example

![logo](https://docsify.js.org/_media/icon.svg ':[class=aCssClass anotherCssClass]')

Is the above correct and is it clear?

Thanks very much!

Koooooo-7 commented 3 months ago

Class names


![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass')

This is current config way in docsify and doesn't support multi values. It will be supported in v5+ and removal in v6.


Multiple classes can be applied to an image by the use of double curly brackets, for example

```md
![logo](https://docsify.js.org/_media/icon.svg '{{ class: aCssClass anotherCssClass}}')

Ideally, this is how we can do in v5+ to support multi values. And in v6-, It's the only way to config with single or multi values.

The new config syntax is still under discussion to make sure it covers all cases. We need go through current exist config formats first and decide what the best new config format is.

paulhibbitts commented 3 months ago

Thanks for the feedback and additional details @Koooooo-7 🙂 I've updated my little documentation example with both formats as an additional reference as things proceed. After writing out these examples I now tend more towards the colon style a bit more than before.

Koooooo-7 commented 3 months ago

Thanks for the feedback and additional details @Koooooo-7 🙂 I've updated my little documentation example with both formats as an additional reference as things proceed. After writing out these examples I now tend more towards the colon style a bit more than before.

Yes, the colon is more convenient. I suppose the point for the changes is we need a obvious docsify config block. What the config rules within this block, either colon or other style we could reconsider also.

docsifyjs / docsify