feature: support customized sidebar item name from content #1825

Jacco-V · 2022-06-22T16:18:40Z

Add support for setting a customized sidebar item name from the documentation markdown content

Summary

This feature add support for specifying custom sidebar item names (especially for long titles) in the documentation markdown files, so that a the custom (typically shortened) item name is used in the sidebar:

## How would I write an "hello, world" example? :sidebar="hello world?"

What kind of change does this PR introduce?

Feature

For any code change,

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

Does this PR introduce a breaking change? (check one)

Yes
No

If yes, please describe the impact and migration path for existing applications:

Related issue, if any:

Tested in the following browsers:

vercel · 2022-06-22T16:18:45Z

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

Name	Status	Preview	Updated
docsify-preview	✅ Ready (Inspect)	Visit Preview	Sep 12, 2022 at 2:15PM (UTC)

codesandbox-ci · 2022-06-22T16:20:11Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 03fda8b:

Sandbox	Source
docsify-template	Configuration

… markdown content

julienw · 2022-06-22T20:29:01Z

src/core/render/compiler.js

      nextToc.slug = url;
      _self.toc.push(nextToc);

-      return `<h${level} id="${slug}"><a href="${url}" data-id="${slug}" class="anchor"><span>${str}</span></a></h${level}>`;
+      return `<h${level} id="${slug}"><a href="${url}" data-id="${slug}" class="anchor"><span>${title}</span></a></h${level}>`;


I haven't tried the patch, but looking at this I would think that the sidebar text would also be used in the rendered page, but I don't think this is correct. We want the sidebar text in the sidebar but not in the page.

Have you tried this? :-)

No, I have not tried the changes, because I do not have a working frontend development environment. (I'm just a backend dev giving this a try).

Also, where can I find the automated tests for this file?

create a _sidebar.md https://docsify.js.org/#/more-pages?id=sidebar

Jacco-V · 2022-06-23T09:57:02Z

I pushed some changes, but it does not work as expected :(
It seems that the :sidebar="hello world?" does not get parsed as config?

## How would I write an "hello, world" example? :sidebar="hello world?"

could it be that the config values read by getAndRemoveConfig do not support quoted strings?

https://github.com/docsifyjs/docsify/blob/1e46f2bd1dbb178ede006dbd9d05fb64e8e34b5a/src/core/render/utils.js#L21=L40

Jacco-V · 2022-06-23T20:53:25Z

I've added quoted string support to the getAndRemoveConfig function and updated the tests. But I'm touching more code than I feel comfortable.

and it is kinda hard to know if things are working as expected without a working dev environment; it would be most helpful if somebody could review the changes.

Jacco-V · 2022-07-03T12:36:10Z

Any chance anyone of the reviewers is going to review this?

Because the provided `str` argument has been html-escaped, with backslashes stripped, we can unfortunately not support escaped characters in quoted strings.

Jacco-V · 2022-07-04T11:35:14Z

Code has been tested and is working as intended, with the sole caveat that:

we cannot support escaped characters in quoted-string config-values, because by the time the str is passed to the getAndRemoveConfig() method, it has been html-escaped, possibly smartypantsified, and backslashes have been stripped. However, I expect his will not be an issue for the large majority of use cases.

Changes can be seen in action in Docsify > Guide > Helpers documentation.

src/core/render/utils.js

Jacco-V · 2022-08-09T11:20:38Z

bump

Jacco-V · 2022-08-28T11:26:24Z

Hi,
Is anyone going to review this PR? or is this functionality somehow not good enough?

Cheers,

Koooooo-7

Hi @Jacco-V , Custom sidecar item name is a good purpose.
Personally, I m considering what is the good mark to define a config content , whether we should use the " here or not . therefore I may not approve this immediately.

For the instance, based on this PR , using the mark to include content means this mark can not be used. i.e.
If using " as the mark ( :sidebar="content"), we can not use the " such as :sidebar="the include " content " like you mentioned.
Instead, if we change the mark to :sidebar={#"any content {in here}"} like:

    str = str
      .replace(
         /(?:^|\s):([\w-]+:?)=?([\w-%]+|{#.*})?/g,
        function (m, key, value) {
          if (key.indexOf(':') === -1) {
            config[key] = (value && value.replace(/{#|}$/g, '')) || true;
            return '';
          }

          return m;
        }
      )
      .replace(/^('|")|('|")$/g, '')
      .trim();

we can get this thing :

The point is what the mark should be the common rule/guidline for those exist/future config and it should not be very common use in user content.

Any ideas?

Jacco-V · 2022-08-30T10:40:15Z

@Koooooo-7 Yes, I can see what you mean.

Architecturally speaking, it would be best if the str argument would be passed to the getAndRemoveConfig() function before the markdown has been transformed into html.

If this was the case, we could fully support quoted strings, including escape characters. This would mean you get clean code and the benefit of a using a syntax everybody knows.

:sidebar="In quoted strings we can normally use escaped \" characters"

However, I'm not sure it is possible to do this, without significant changes to the code base. Having said that, from an architectural point of view, it would still be the best option.

Another option would be to replace the regular-expression based 'parsing' with an actual parser, which would be able to handle escape charters even in the html formatted str argument. This option would get the quoted strings working, without addressing the architectural issue, but the end-user won't see the difference.

The other option could be as you propose: go for a different set of start of string and end of string markers. This would sidestep the problem. The code-changes would be more simple, at the cost introducing a custom format instead of using quoted strings and not addressing the architectural issue.

In the end, it is not up to me to choose which option is best suited for this project: I'm not one of the project members; I'm just a back-end guy who contributed a pull-request.

Koooooo-7 · 2022-08-30T11:13:12Z

@Jacco-V Thx for your input !
About change the regex to parser for configs is a good idea but we have not moved forward to it yet.
And exposing the getAndRemoveConfig as a hook is on the road. I suppose this hook could let user to custom config tpl more flexible, we could only provide a happy path one by default.

jhildenbiddle · 2022-09-09T16:53:14Z

@Jacco-V @Koooooo-7 --

I haven't tested this PR, but perhaps we can work with the escaped character limitations using one of the following approaches:

Allow titles to be wrapped in single or double quotes. This allows for either quote type to be used within the string without needing to be escaped:
```
:sidebar="Single 'quotes' here"
```
```
:sidebar='Double "quotes" here'
```

Use HTML entities

:sidebar='Double &quot;quotes&quot; here'

FWIW, I would also change the "Customize..." sidebar labels to the following:

Helpers > Heading IDs
Helpers > Sidebar Titles

These labels align with the other sidebar labels under the "Helpers". As an added bonus, it removes the "customise vs customize" localization issue. I know that's not the goal of this PR, but hey, while we're here... :)

Koooooo-7 · 2022-09-10T16:00:26Z

@jhildenbiddle How you doing ~

About the Customize changes, I think it is a nice change to make the label more plain and understandable.

The "/' approach it sounds both fine. The more importance thing to me is the now and further enrichment configs, I think we should refactor getAndRemoveConfig to be more flexible parser(s) for configs, otherwise , the regex would be more and more complex and messy.

Jacco-V · 2022-09-12T09:26:41Z

@jhildenbiddle This is a possibility, and it could be an intermediate solution, but it would also be another incarnation of 'sidestepping the problem', although with a better solution than introducing custom start of string and end of string markers (in my opinion).

However, by sidestepping the problem, you continue building on non-robust legacy choice and will need to add increasingly complex regular expression(s) to hammer the non-ideal setup into a working solution. So, I agree with @Koooooo-7: Going the getAndRemoveConfig hook, with a parser way, you get more flexible, more robust, and easier to maintain code.

jhildenbiddle · 2022-09-12T14:13:57Z

@Jacco-V, @Koooooo-7 --

No arguments from me about the issues with building upon problematic legacy code. My comment was intended only to propose a way to make the stated drawback of this PR -- the inability to support escaped characters in quoted-string config-values -- less of an issue so that we can deliver a solution sooner. If someone wants to take a crack at doing things the "better" way, I'm all for it.

Jacco-V mentioned this pull request Jun 22, 2022

Support specifying short-titles for the sidebar from content pages? #1821

Open

vercel bot deployed to Preview June 22, 2022 16:19 View deployment

Implement support for setting a customized sidebar item name from the…

eb5f939

… markdown content

Jacco-V force-pushed the feature-customizableSidebarItemName branch from 22580b7 to eb5f939 Compare June 22, 2022 16:44

vercel bot deployed to Preview June 22, 2022 16:45 View deployment

julienw reviewed Jun 22, 2022

View reviewed changes

Jacco-V added 3 commits June 23, 2022 11:31

Push both title and label to toc (=table of contents) array

a764b02

Apply changes to duplicate code block

cfca427

Apply new functionality to doc file

cdca395

vercel bot deployed to Preview June 23, 2022 09:37 View deployment

Refactor for better readability

f536e72

vercel bot deployed to Preview June 23, 2022 09:51 View deployment

Support quoted strings for config value arguments

e581df7

vercel bot deployed to Preview June 23, 2022 20:05 View deployment

Update render-util tests

27513e0

vercel bot deployed to Preview June 23, 2022 20:43 View deployment

replace function chaining with more modified regex

cf9e00b

vercel bot deployed to Preview June 23, 2022 20:48 View deployment

sy-records requested a review from a team July 3, 2022 14:30

Jacco-V added 2 commits July 4, 2022 10:19

replace 'label' with 'text' for more intuitive variable naming

83e5795

Fix incorrect (escaped) quoted string parsing

b838fc3

vercel bot deployed to Preview July 4, 2022 08:21 View deployment

Fix logic for html-escaped str argument

da7937e

Because the provided `str` argument has been html-escaped, with backslashes stripped, we can unfortunately not support escaped characters in quoted strings.

vercel bot deployed to Preview July 4, 2022 08:54 View deployment

Fix test arguments to match reality

d66d22d

Jacco-V added 2 commits July 4, 2022 11:50

Change test to provide html-escaped string

71288be

Change regex to work directly on html-escaped string

79e738a

vercel bot deployed to Preview July 4, 2022 09:52 View deployment

Add support for marked.md smartypants 'smart' quotes

a6333ec

vercel bot deployed to Preview July 4, 2022 10:23 View deployment

Jacco-V requested a review from sy-records July 4, 2022 13:11

Koooooo-7 added the tests label Jul 10, 2022

Koooooo-7 reviewed Jul 10, 2022

View reviewed changes

src/core/render/utils.js Show resolved Hide resolved

sy-records requested a review from Koooooo-7 August 29, 2022 00:34

Merge branch 'develop' into feature-customizableSidebarItemName

5a1e655

vercel bot deployed to Preview August 30, 2022 07:27 View deployment

Koooooo-7 reviewed Aug 30, 2022

View reviewed changes

Koooooo-7 added needs discussion blocked and removed tests labels Aug 31, 2022

Merge branch 'develop' into feature-customizableSidebarItemName

03fda8b

vercel bot deployed to Preview September 12, 2022 14:15 View deployment

Koooooo-7 mentioned this pull request Sep 20, 2022

Bug: Docsify's path handling is problematic (and broken in some scenarios) #1891

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feature: support customized sidebar item name from content #1825

feature: support customized sidebar item name from content #1825

Jacco-V commented Jun 22, 2022 •

edited

Loading

vercel bot commented Jun 22, 2022 •

edited

Loading

codesandbox-ci bot commented Jun 22, 2022 •

edited

Loading

julienw Jun 22, 2022

Jacco-V Jun 22, 2022 •

edited

Loading

Jacco-V Jun 23, 2022 •

edited

Loading

sy-records Jun 23, 2022

Jacco-V commented Jun 23, 2022 •

edited

Loading

Jacco-V commented Jun 23, 2022 •

edited

Loading

Jacco-V commented Jul 3, 2022

Jacco-V commented Jul 4, 2022 •

edited

Loading

Jacco-V commented Aug 9, 2022

Jacco-V commented Aug 28, 2022

Koooooo-7 left a comment

Jacco-V commented Aug 30, 2022 •

edited

Loading

Koooooo-7 commented Aug 30, 2022

jhildenbiddle commented Sep 9, 2022 •

edited

Loading

Koooooo-7 commented Sep 10, 2022

Jacco-V commented Sep 12, 2022

jhildenbiddle commented Sep 12, 2022 •

edited

Loading

feature: support customized sidebar item name from content #1825

Are you sure you want to change the base?

feature: support customized sidebar item name from content #1825

Conversation

Jacco-V commented Jun 22, 2022 • edited Loading

Summary

What kind of change does this PR introduce?

For any code change,

Does this PR introduce a breaking change? (check one)

Related issue, if any:

Tested in the following browsers:

vercel bot commented Jun 22, 2022 • edited Loading

codesandbox-ci bot commented Jun 22, 2022 • edited Loading

julienw Jun 22, 2022

Choose a reason for hiding this comment

Jacco-V Jun 22, 2022 • edited Loading

Choose a reason for hiding this comment

Jacco-V Jun 23, 2022 • edited Loading

Choose a reason for hiding this comment

sy-records Jun 23, 2022

Choose a reason for hiding this comment

Jacco-V commented Jun 23, 2022 • edited Loading

Jacco-V commented Jun 23, 2022 • edited Loading

Jacco-V commented Jul 3, 2022

Jacco-V commented Jul 4, 2022 • edited Loading

Jacco-V commented Aug 9, 2022

Jacco-V commented Aug 28, 2022

Koooooo-7 left a comment

Choose a reason for hiding this comment

Jacco-V commented Aug 30, 2022 • edited Loading

Koooooo-7 commented Aug 30, 2022

jhildenbiddle commented Sep 9, 2022 • edited Loading

Koooooo-7 commented Sep 10, 2022

Jacco-V commented Sep 12, 2022

jhildenbiddle commented Sep 12, 2022 • edited Loading

Jacco-V commented Jun 22, 2022 •

edited

Loading

vercel bot commented Jun 22, 2022 •

edited

Loading

codesandbox-ci bot commented Jun 22, 2022 •

edited

Loading

Jacco-V Jun 22, 2022 •

edited

Loading

Jacco-V Jun 23, 2022 •

edited

Loading

Jacco-V commented Jun 23, 2022 •

edited

Loading

Jacco-V commented Jun 23, 2022 •

edited

Loading

Jacco-V commented Jul 4, 2022 •

edited

Loading

Jacco-V commented Aug 30, 2022 •

edited

Loading

jhildenbiddle commented Sep 9, 2022 •

edited

Loading

jhildenbiddle commented Sep 12, 2022 •

edited

Loading