Local non-md file links are still hashed by docsify

[backspaces]

TL;DR: How do I create links in my .md files that are not hashed by docsify?

Details: I have a link in my .md files that looks like: [hello world](/tutorial/?hello)

The /tutorial/index.html uses a query string to select the js file to run, here hello.js.

Clicking on the link gives a 404 error due to hashing the url:

GET http://localhost/src/asx/docs/tutorial/README.md 404 (Not Found)
http://localhost/src/asx/docs/#/tutorial/?hello=undefined

If I convert to [hello world](/tutorial/index.html?hello) I still get a hash conversion and an undefined error:

http://localhost/src/asx/docs/#/tutorial/index.html?hello=undefined
GET http://localhost/src/asx/docs/tutorial/_sidebar.md 404 (Not Found)

If I remove the hash to either of:

http://localhost/src/asx/docs/tutorial/?hello
http://localhost/src/asx/docs/tutorial/index.html?hello

and directly paste into the url bar, both work as expected.

If I use either of these complete urls in the .md file, it also works, but that fails to work on both my local system and github due to the differences in the url paths.

I also tried building an alias for /tutorials that uses document.location

'/tut': ${document.location.href.replace(/#.*/,'')}tutorial/,

.. which produces:

/tut: "http://localhost/src/asx/docs/tutorial/"

..thus solves the issue of github/localhost differences.

but using [hello world](/tut/?hello) fails, apparently the alias needs to be the entire path?

How do I create links in my .md files that are not hashed by docsify?

[backspaces]

More info: I tried the markdown renderer option:

    markdown: {
      renderer: {
        link: function (href, title, text) {
          console.log('link', href, title, text)
          return `<a href="${href}"> </a>`
        }
      }
    },

as a test to see if I could simply capture the links and make sure the ones I cared about were not hashed. To my surprise, I did not get these links, apparently docsify uses the same marked hook and it does not get allow docsify users to use it too.

It seems to me this is a docsify bug, it should chain the user's link renderer to the end of it's use. Or, is there a way I can call your link renderer after I convert my links to complete urls, http://path/to/my/docs/tutorial/?hello, which you do not hashify.

How can I share the marked link renderer with docsify, either pre or post?

The bottom line is this: user's markdown should Just Work, just as if it were in any other markdown environment .. like the github wiki.

Hashifying the links should be controllable in the docsify index.html file. At least the window.$docsify should allow some way for the user to specify links/dirs to not be hashed.

[backspaces]

Would a hook work for this? I.e. use one of the hooks to remove the /#/'s where I don't want docsify to manage my links?

[QingWei-Li]

TL;DR: How do I create links in my .md files that are not hashed by docsify?

Currently you can solve this problem by writing the full URL. For example

# This is full URL

[hello world](//example.com/tutorial/?hello)

Or via HTML tag

# Headline

<a href="/tutorial/?hello">hello world</a>

[backspaces]

Thank you for the quick response! I appreciate it. And I really love docsify, brilliant project.

I would like us to consider this a bug or enhancement, but also hope we can find a work-around.

Why? It is very natural for us to include examples in our documentation. If I use the docs/*.md files by themselves, without docsify (github for example, or my own use of marked.js), I naturally do not have this problem. So I believe you will find users of docsify expecting (foo)[bar/baz.html] to Just Work as markdown expects.

The full url solution does not work well because while developing on localhost, I will need a different full URL than when deployed on github.

Workaround:

• markdown: I should be able to write my own markdown.renderer.link function which converts my tutorial/?hello link into a full link based on document.location. I believe, however, I would still need to call your link renderer too, right? My experiment above did write the link info to console but caused docsify to fail. Possibly I should repeat it, converting the result to a full URL, and that should work?
• hook: I haven't tried it yet, but .. do you think I could use a hook to convert a relative link to a full URL? I'm not certain which hook would be appropriate.
• aliases: I could not make them work, and I would prefer to not use them because they create .md files that would not work elsewhere, such as the github wiki.

Solution:

• Documentation: Possibly we find a workaround we like and simply document it. This should not require changes to the .md if at all possible, but instead use window.$docsify settings.
• Docsify Ignore: have an ignore feature in window.$docsify which tells docsify to not hashify certain directories within docs/
• Convention: If a relative url is used in a .md link, and does not point to a .md file itself, then do not hash. I think you already handle this for image files, right?
• Your better solution! I'm sure you could derive a good solution based on the architecture.

Goal: To have a solution for certain relative links within docs/ not be hashed, all within the window.$docsify object. This can be a workaround, or a new feature. It should not require changes to the markdown .. the markdown files should work well wherever they are used such as on github itself.

Let me know if there is a workaround I can try now! Thanks!

[backspaces]

OK, I found a workaround using a hook. It's pretty hacky but is good enough for now:

  // before defining $docsify:
  const root = document.location.href.replace(/#.*/,'')
...
    plugins: [
      function(hook, vm) {
        hook.beforeEach((markdown) => {
          const result = markdown.replace(/]\(tutorial\//g, `](${root}/tutorial/`)
          return result
        })
      }
    ],

The regex is likely not the safest, and it really should take an array of directory names to be more general. And probably I should use the vm to get the docs/ URL.

A better approach is likely to use markdown.renderer.link, right?

[QingWei-Li]

I have a idea. We know that markdown's link syntax can pass three parameters, likes

[abc](/abc?hello "title")

will be compiled to
<a href="/#/abc?hello" title="title">abc</a>

So, I can provide a special placeholder (likes :ignore) that tells docsify that does not need to compile this. For example

[abc](/abc?hello ":ignore title")

will be compiled to
<a href="/abc?hello" title="title">abc</a>

Perhaps this can solve your problem, and I think it is easier to use (we only need to explain in the documentation).

[backspaces]

Interesting!

• Pros: Simple, no JS computation of global URL
• Cons: Docsify-specific markdown, .md's may be odd in other contexts, CDNs

I would prefer to not solve it in a docsify-specific way. But I would use it if it were available, for sure. Possibly :nodocsify to distinguish from other md based CDNs? No big deal tho.

But lets look at this from a higher, architectural, point of view.

Users will not be surprised that images work correctly. They do not appear to be hashed.

For example, I have a data/ dir for images and other resources. When I write:
![image with patches, turtles, links](data/allagents.jpg)
it does not produce a hashed URL.

However, users will be surprised when their relative links act differently.

So my question is: Do we need to treat anchor md links differently than image links?

I admit to ignorance here .. I'm sure there are places where users do want docsify to manage the link, for example when linking to other .md files. Are there others?

So is there a middle ground here? A way to not hashify all relative links? I would be fine with a rule that only hashified .md links for example. Or a special syntax for when I do want docsify to manage the link .. maybe /#/foo/bar/ say?

Finally, the issue of not modifying the .md files for docsify. I think the main issue was, as far as I can tell, both the user and docsify use the link marked renderer function. Is there a safe way for us to share link function?

Thank you for your patience!

[QingWei-Li]

I think the main issue was, as far as I can tell, both the user and docsify use the link marked renderer function. Is there a safe way for us to share link function?

Now you can only override the default rendering function by configuration. Maybe I can provide another special rendering function, such aspreLink? But I do not think it's a good idea. If you think it can be solved, I will provide it.

[QingWei-Li]

Or maybe I can provide a option to Ignore to compiled the link, for example

window.$docsify = {
  noCompileLinks: [
    '/foo',
    '/data/.*' // supports regular expression
  ]
}

[backspaces]

No, let's go with your idea, I think it's fine. To tell the truth, I didn't even know there was a title included with the url! Blush. :)

Docsify is really fun to work with, btw. I've been working on documenting my repo and so far so good!

[backspaces]

That would be really interesting if it is possible. Very sophisticated, IMHO. I don't really understand the hashed urls and how they fit into the CMS you are using. I noticed you have contributed to Vue so I presumed it was related, somehow. Is Vue as interesting as it seems? I read an article that said that both React and Angular were built by large companies interested in large projects, while Vue was written by a single person interested in small, simple projects. I like it!

[QingWei-Li]

Because in fact we have only one entry file which is the index.html in the root directory. If we use the usual url, likes //example.com/foo, It will not be accessible because /foo.html does not exist at all.

So we need hash router. We need an entry file, the route is managed in js.