[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Introduce a new docsify config for markdown enrichment #2476

Open
Koooooo-7 opened this issue Jul 30, 2024 · 4 comments
Open

Introduce a new docsify config for markdown enrichment #2476

Koooooo-7 opened this issue Jul 30, 2024 · 4 comments
Labels
needs discussion
Milestone
5.x

Comments

@Koooooo-7
Copy link
Member
Koooooo-7 commented Jul 30, 2024 •
edited
Loading

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.
@Koooooo-7 Koooooo-7 mentioned this issue Jul 30, 2024
Closed
6 tasks
@Koooooo-7 Koooooo-7 added this to the 5.x milestone Jul 30, 2024
@Koooooo-7 Koooooo-7 reopened this Aug 5, 2024
@paulhibbitts
Copy link
Collaborator
paulhibbitts commented Aug 5, 2024 •
edited
Loading

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
Copy link
Member Author

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
Copy link
Collaborator
paulhibbitts commented Aug 6, 2024 •
edited
Loading

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
Copy link
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
needs discussion
Projects
None yet
Milestone
5.x
Development

No branches or pull requests
2 participants
@paulhibbitts @Koooooo-7