refactor: rewrite getAndRemoveConfig(str) function

[Koooooo-7]

Summary

Reactor getAndRemoveConfig(str) function to a generic Lexer instead of a complex regex.
Correct current behavior and indicate docsify needs to resolve valid config keys. Warning invalid configs also.

Remove to use a tricky returned title as config options.
Instead, new KEY_appened_props introduced.

It will let the config parse as :KEY=VALUE append_props..., each config processor can handle its own logic
for the Value and append_props. e.g.

:class=classA classB classC :include
The classA assigns to class=classA, the rest of classB classC add to class_appened_props.

config

{
  class: "classA",
  class_appened_props: "classB classC",
  include: true
}

Which can support multi values configs of one key such as #2471 .

Related issue, if any:

What kind of change does this PR introduce?

Refactor

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

Yes
No

Tested in the following browsers:

• Chrome
• Firefox
• Safari
• Edge

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docsify-preview	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 24, 2024 0:33am

[jhildenbiddle]

@Koooooo-7 --

1. How does this handle multiple attributes when multiple values are provided?

   [Text](page.md ':target=_blank :class=foo bar')
   [Text](page.md ':class=foo bar :target=_blank ')

   I would have assumed multiple values would need to be wrapped in quotes:

   [Text](page.md ':target=_blank :class="foo bar"')
   [Text](page.md ':class="foo bar" :target=_blank ')

2. Can we fix the "strict quote at star/end the configs" by trimming spaces and line endings from the start and end of the string found between quotes? If we don't, a single extra space could throw errors which may be hard to track down.

3. Why not just apply all attribute names and values regardless of whether they are "known"? This would allow people to add things like data attributes to elements in markdown.

   [Text](page.md ':foo=bar :data-baz=buzz')

   <a href="..." foo="bar" data-baz="buzz">Text</a>

[paulhibbitts]

Thanks very much @Koooooo-7 for this! I've put my original CodeSandbox example online with your Docsify Preview build and @jhildenbiddle examples to help with testing - looking good so far 🙂 https://paulhibbitts.github.io/docsify-v5-preview/#/test-3

[Koooooo-7]

@Koooooo-7 --

1. How does this handle multiple attributes when multiple values are provided?

   [Text](page.md ':target=_blank :class=foo bar')
   [Text](page.md ':class=foo bar :target=_blank ')
   

It will be resolve to

{
  target: "_blank",
  class: foo,
  class_appened_props: "bar"
}

Cos the append props will look back to the first leading KEY.

---

2. Can we fix the "strict quote at star/end the configs" by trimming spaces and line endings from the start and end of the string found between quotes? If we don't, a single extra space could throw errors which may be hard to track down.

I see, will refactor to retrieve the closest pre/next '/" instead.

3. Why not just apply all attribute names and values regardless of whether they are "known"? This would allow people to add things like data attributes to elements in markdown.

   [Text](page.md ':foo=bar :data-baz=buzz')
   

Gotcha. Will update to clean the whole config blocks and only retrieve docsify valid config tokens.

[Koooooo-7]

Hi @jhildenbiddle ---
Already update:

• Support loose quote ' :class=any :include '
• Support unknown attributes ':class=foo :foo=bar'

And I add more test cases and comments on those cases we discussed.

[paulhibbitts]

Thanks so much @Koooooo-7 , this is going to be a really nice improvement 🙂 I've updated my online Docsify Preview build with your latest Preview and things look good! https://paulhibbitts.github.io/docsify-v5-preview/#/test-3

[Koooooo-7]

Thanks so much @Koooooo-7 , this is going to be a really nice improvement 🙂 I've updated my online Docsify Preview build with your latest Preview and things look good! https://paulhibbitts.github.io/docsify-v5-preview/#/test-3

Thx for you live preview for the changes !!!

[jhildenbiddle]

Suggestion on this:

1. How does this handle multiple attributes when multiple values are provided?

   [Text](page.md ':target=_blank :class=foo bar')
   [Text](page.md ':class=foo bar :target=_blank ')
   

It will be resolve to

{
  target: "_blank",
  class: foo,
  class_appened_props: "bar"
}

Instead of capturing multiple values using class and class_appended_props properties, why not require multiple values to be wrapped in quotes? This seems more natural since it is how attributes and values work in HTML. It will also make it easier to read multiple attribute values because all values are contained in a single property.

For example:

[Text](page.md ':foo :target=_blank :class="bar baz" This is the title')

{
  foo: true,
  target: "_blank",
  class: "bar baz",
  title: "This is the title" // links support title attribute in markdown
}

The rules would then be:

1. All attributes must start with :
2. Attributes without values are valid (:foo)
3. Quotes are optional for single values (:target=_blank or :target="_blank")
4. Quotes are required for multiple attribute values (:class="bar baz"')

The question is then if/how we want to handle stray, unquoted values. Consider the following example:

[Text](page.md ':foo=val1 val2 :bar=val3 val4'). // Missing quotes around multiple values

I would expect this to produce the following:

{
  foo: "val1",
  bar: "val3",
  title: "val4",
}

What happens to val2?

The easiest thing to do would be to just drop val2 because according to the rules this is neither an attribute (does not start with :) or an attribute value.

Thoughts?

[Koooooo-7]

Instead of capturing multiple values using class and class_appended_props properties, why not require multiple values to be wrapped in quotes? This seems more natural since it is how attributes and values work in HTML. It will also make it easier to read multiple attribute values because all values are contained in a single property.

For example:

[Text](page.md ':foo :target=_blank :class="bar baz" This is the title')

{
  foo: true,
  target: "_blank",
  class: "bar baz",
  title: "This is the title" // links support title attribute in markdown
}

The rules would then be:

1. All attributes must start with :
2. Attributes without values are valid (:foo)
3. Quotes are optional for single values (:target=_blank or :target="_blank")
4. Quotes are required for multiple attribute values (:class="bar baz"')

That would be more clearly. but it brings a breaking change for all the config rules for now. So I choose a compromise way to make it and doesn't breaking anything to get ride of the regex.

Besides, the config of docsify is not that consistent.
On the config class, it looks they should be as the same value.
But such as :type=code js or :ignore title.
It's not a same thing to the config Key, more likely a random appendix for current config depends on what the config support.

The question is then if/how we want to handle stray, unquoted values. Consider the following example:

[Text](page.md ':foo=val1 val2 :bar=val3 val4'). // Missing quotes around multiple values

I would expect this to produce the following:

{
  foo: "val1",
  bar: "val3",
  title: "val4",
}

What happens to val2?

The easiest thing to do would be to just drop val2 because according to the rules this is neither an attribute (does not start with :) or an attribute value.

Thoughts?

It is hard to say a data attribute nor a docsify config within a string.

If we decided include a breaking change on this. I think we can introduce a docsify config block. e.g.

[Text](page.md ' docsify=[:foo :target=_blank :class=bar baz]  This is the title')

Then, we have a clear line to distinguish between the docsify part and custom made for markdown owned.

[jhildenbiddle]

That would be more clearly. but it brings a breaking change for all the config rules for now. So I choose a compromise way to make it and doesn't breaking anything to get ride of the regex.

Besides, the config of docsify is not that consistent.

Makes sense. I didn't realize that the attribute parser is inconsistent across tags. I appreciate trying to not introduce a non-breaking change, but perhaps this is the opportunity make attribute parsing consistent in docsify for all markdown tags that support it. See below...

If we decided include a breaking change on this. I think we can introduce a docsify config block. e.g.

[Text](page.md ' docsify=[:foo :target=_blank :class=bar baz]  This is the title')

Then, we have a clear line to distinguish between the docsify part and custom made for markdown owned.

Can we add something like the proposed "block" of attributes above as a new v5 feature but retain the existing :prop=val behavior for backwards compatibility? This would allow us to update our docs with the new "preferred" method alongside the older :prop=name method, but note in the docs that the older method is deprecated in v5 and will be removed in v6.

For example, we can drop the docsify= and use the : as the start of the pattern:

[Text](page.md ':[foo target="_blank" class="bar baz"]  This is the title')

Alternatively, we could use single or double brackets to start/end the pattern which would make it easy for us to parse using JSON.stringify once the string was extracted:

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

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

If we go this route, I would propose we not allow mixing new and old attribute styles like this:

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

Doing this promotes continued use of the old :prop=name style. When this happens, we can either handle both old and new styles with a warning in the console, or we can process only the new style and ignore the older :prop style.

This seems like a better approach than updating the getAndRemoveConfig function with new capabilities that only work in some scenarios and don't address Docsify's inconsistencies in markdown attribute parsing.