Introduce a new docsify config for markdown enrichment

[Koooooo-7]

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]

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]

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]

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]

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.

[paulhibbitts]

Just a note that this looks pretty important for Docsify v5, as right now there does not seem to be a way to style a button as primary or secondary via Markdown as only one class seems to be recognized?

For example:

<a href="https://canvas.sfu.ca/courses/44038/quizzes/166553" class="button primary">Required Reading Quiz due Jun 4th</a>

Which could be rendered via Markdown with this new feature:

[Required Reading Quiz due Jun 4th](https://canvas.sfu.ca/courses/44038/quizzes/166553 '{{ class: button primary }}')

OR (preferred by me at this point)

[Required Reading Quiz due Jun 4th](https://canvas.sfu.ca/courses/44038/quizzes/166553 ':[class=button primary]')

[Koooooo-7]

Just a note that this looks pretty important for Docsify v5, as right now there does not seem to be a way to style a button as primary or secondary via Markdown as only one class seems to be recognized?

Indeed, docsify currently doesn't support multiple values in class. We need refine the configured mechanism in v5, need discussion on it.

[paulhibbitts]

Thanks @Koooooo-7 , is there anything I can contribute?

[Koooooo-7]

Thanks @Koooooo-7 , is there anything I can contribute?

Hi @paulhibbitts I would appreciate that there could have some research on the conventional config usages examples in other docs relevant project which should make us have more reasonable proposal on discussion.

[paulhibbitts]

Hi @Koooooo-7 , I've done a bit of research and thought I would loop-back to see if I am after the right info to help 🙂

I first looked at some other online publishing doc tools, incl. Mkdocs, ReadTheDocs, GitBook, and Docusaurus and was not able to see such an ability provided by default.

I then researched how general Markdown packages might handle applying CSS to content, and their syntax, and I found several examples using single curly brackets: https://michelf.ca/projects/php-markdown/extra/#spe-attr https://kramdown.gettalong.org/syntax.html#inline-attribute-lists https://www.npmjs.com/package/markdown-it-attrs

I also found this for 11ty: https://dev.to/giulia_chiola/add-html-classes-to-11ty-markdown-content-18ic

So the use of curly brackets seems to be more common, while I find the use of a colon more familiar as a user of Docsify.

I also created a little Markdown file on GitHub, to see how things are displayed there in the hopes of avoiding markup that causes unwanted visual issues etc. https://github.com/paulhibbitts/Markdown-File-Tests/blob/main/defining-multiple-clases.md

I also included a few possible examples of apply CSS classes to text elements for future consideration etc.

Please let me know if the above is helpful, thanks!

[paulhibbitts]

Any additional thoughts on this issue @Koooooo-7 ?

[cagix]

pandoc also uses curly brackets, e.g. for defining attributes to images or code blocks and other elements: https://pandoc.org/MANUAL.html#extension-link_attributes

syntax is {#id .class key=val key2="foo bar"}

[Koooooo-7]

Any additional thoughts on this issue @Koooooo-7 ?

I'm still struggling on this, cuz I reviewed our discussion of the configs design. @jhildenbiddle said an very import view to me and I haven't find a way to handle it yet.

Document portability is arguably the most critical feature of markdown, so I personally am not a fan of extensions which result in unsupported syntax rending as content when moved between markdown environments.

So I'm considering to implement it which both combined the {{ ...config }} and the style of <!-- {docsify-ignore} --> to make configs keep the portability.

On embed MD level, such as IMG, Links, user could config without <!-- { } --> comments syntax since all renders will omit it. On the Content level, such as Title, we could support <!-- { } --> to make it won't show directly on other non-docsify parsers.

Before achieve that, maybe we need an enhancement as workaround first instead of being stagnated.

[paulhibbitts]

This has been merged and tested, so closing issue.