Docsify: Markdown link to site root

[gerjandev]

I am using docsify to create conceptual documentation and its great. But I have one question:

Is it possible to link to the root url of my website in a markdown file?

Example of my app:
api.example.com/swagger
api.example.com/docs (api.example.com/Docs/#/) this is the root for docsify

What I would like to do is to point to the swagger endpoint without knowing the base address, so in a markdown file:

Please go to Swagger ( ../swagger )

The problem is that I do not know the base url (so also no absolute url) because this can switch/change any time.

[jhildenbiddle]

Perhaps I am misunderstanding, but wouldn't /swagger do the trick?

Please go to [Swagger](/swagger)

[SidVal]

Hello, now I understand what he is trying to say.

Check this repo: https://github.com/SidVal/dev.web/tree/master/docs

Structure:

root (dev.web)
  |_ docs (folder)
      |_ .nojekyll
      |_ README.md
      |_ _sidebar.md
      |_ capitulo1.md
      |_ capitulo2.md
      |_ favicon.ico
      |_ index.html 
      |_ clases (folder)
          |_ README.md
          |_ _sidebar.md
          |_ clase1.md
          |_ clase2.md

Site: https://sidval.github.io/dev.web/#/

Well., check this...

The _sidebar.md in the /clases/'s folder, is trying to link the "root" ... how can I do that?

https://github.com/SidVal/dev.web/blame/master/docs/clases/_sidebar.md#L1

I tried with:

• [Inicio](/dev.web) goes to: https://sidval.github.io/dev.web/#/dev.web (404 error)
• [Inicio](https://sidval.github.io/dev.web/#/?id=devweb) goes to "new page", so... did not work.
• [Inicio](../#devweb) goes to: https://sidval.github.io/dev.web/#/clases/../#dev.web (404 error)

How can I do it?

[jhildenbiddle]

If docsify's markdown conversion is the issue, try the link :ignore helper:

Markdown:

[Inicio](/dev.web ':ignore')

HTML Output:

<a href="/dev.web">Inicio</a>

[SidVal]

Thanks for replay @jhildenbiddle

With that tip the results were:

• * [Inicio](../ ':ignore') ➡️ https://sidval.github.io/ (open new tab, so no).
• * [Inicio](/dev.web/#devweb ':ignore') ➡️ https://sidval.github.io/dev.web/#/devweb (new tab, 404)
• * [Inicio](/dev.web/?id=devweb ':ignore') ➡️ https://sidval.github.io/dev.web/?id=devweb#/ (new tab, so no)

Any way to linking the docs root without opening new tab?

[QingWei-Li]

@SidVal https://docsify.js.org/#/configuration?id=externallinktarget

[SidVal]

Thanks for replay @QingWei-Li ... but, if I change the externalLinkTarget, all the site would link to _self, and that is not the idea.

I need that ONE link goes to the root of the site, without opening a new tab

[QingWei-Li]

@SidVal https://docsify.js.org/#/helpers?id=set-target-attribute-for-link

[SidVal]

Thanks @QingWei-Li ... that should work., but...

I put this:
[Inicio](https://sidval.github.io/dev.web/ ':target=_self')

Now you can check the site, and press "Inicio":
<a href="https://sidval.github.io/dev.web/" target="_blank">Inicio</a>

[jhildenbiddle]

It sounds like you need to apply both :ignore and :target=_self to a link. From what I can see, docsify currently supports one or the other, but not both.

It would be nice if docsify had a generic method of applying attributes and docsify-specific flags. For example:

[Link](/path/to/file ':docsifyflag' ':attr1' ':attr2=value')

The docsify flag wouldn't be represented in the HTML output, but the attributes would:

<a href="/path/to/file" attr1 attr2="value">Link</a>

This method would allow the following markdown:

[Inicio](/dev.web/ ':ignore' ':target=_self')

To render this HTML (which I believe is what you're looking for):

<a href="/dev.web/" target="_self">Inicio</a>

As far as your issue is concerned, adding the link to the document using HTML instead of markdown would be another way to work around the docsify's markdown limitations.

[SidVal]

This <a href="/dev.web/" target="_self">Inicio</a> works! :tada:
Last version (v3)

Thanks @jhildenbiddle !

[iolaizola]

In order to create absolute paths, I created a hook that makes the work when ":relative" is added to the links. E.g:

[text](/folder/files.md` ":relative")

This is the hook:

          hook.beforeEach(function (content) { //enabling relative paths
            var url = window.location.href;     // Returns full URL
            lidx = url.lastIndexOf("/");
            xurl = url.substring(0,lidx);
            return content.replace(/\[([^\]]*)\]\(([^)]*)\)/g,
              function(x){
                if (x.includes(":relative")){
                  return x.replace("](","]("+xurl+"/")    
                }
                return x;
              }
            )
          })

[SidVal]

Great @iolaizola can you explain how to add that hook please?

[iolaizola]

Sure,

you have to edit the index.html where there is :

window.$docsify = {

you have to create the environment for plugins if it does not exist:

  plugins: [
        function (hook) {

and then you add the aforementioned function.

Hope it helps,

[grimpy]

An adapted version of the above

        plugins: [
        function (hook) {
        hook.beforeEach(function (content) { //enabling relative paths
            var url = window.location.href;     // Returns full URL
            var lidx = url.lastIndexOf("/");
            var xurl = url.substring(0,lidx);
            var idx = xurl.indexOf("#");
            var purl = xurl.substring(idx + 1, xurl.length);
            return content.replace(/\[([^\]]*)\]\(([^)]*)\)/g,
              function(x){
                if (!x.includes("](/")){
                  return x.replace("](","]("+purl+"/")    
                }
                return x;
              }
            )
          })
        }]

I mainly changed 2 things
I made sure the rewritten urls don't open a new window/tab and I made the detection of the relative page dynamic based if the urls startswith / or not

[jhildenbiddle]

@SidVal, @iolaizola, @grimpy --

Friendly docsify compatibility reminder:

The code listed above will break IE due to the use of String.prototype.includes(). Fortunately, includes() can be easily swapped out for regex.test() or indexOf() for IE compatibility.

[iolaizola]

Great job @grimpy

i just included an exception when the Docsify label "ignore" is used.

var url = window.location.href;     // Returns full URL
lidx = url.lastIndexOf("/");
xurl = url.substring(0,lidx);
var idx = xurl.indexOf("#");
var purl = xurl.substring(idx + 1, xurl.length);
var root_url = xurl.substring(0,idx-1);

content = content.replace(/\[([^\]]*)\]\(([^)]*)\)/g,  //enabling relative paths as they should be (by adding "/" in the beginning)
function(x){
  if (!x.includes("](/")){
      if(x.includes(":ignore")){
          return x.replace("](","]("+root_url+purl+"/") ;   
       }
       return x.replace("](","]("+purl+"/") ;   
     }
     return x;
} )

[iolaizola]

Here again,
I let a complete hook that:

• deals with relative paths
• enables the use of "../" to go upwards in the directory tree
• detects all no ".md" extensions or folders ("/") to automatically "ignore" the rest of content.
• does not process external links ("http://" or "https://)

 hook.beforeEach(function (content) { //enabling relative paths (".." not allowed by now)
            var url = window.location.href;     // Returns full URL
            lidx = url.lastIndexOf("/");
            xurl = url.substring(0,lidx);
            var idx = xurl.indexOf("#");
            var purl = xurl.substring(idx + 1, xurl.length);
            var root_url = xurl.substring(0,idx-1);

            content = content.replace(/(.)?\[([^\]]*)\]\(([^)]*)\)/g,  //enabling relative paths as they should be (by adding "/" in the beginning)
              function(x){
                if (x.includes("![")){ // don't process images
                  return x;
                }
                if ( /\(\s*http(s)?:\/\//.test(x) ){ //don't process external links
                  return x;
                }
                while (x.includes("../")){ //enable "outter folders" in relative paths
                  var the_arr = purl.split('/');
                  the_arr.pop();
                  purl = the_arr.join('/') ;
                  x = x.replace("../","")
                }

                if ( !/\((.*?).md(\s|\))/.test(x) ){ // Automatically add ":ignore" to all not ".md" links
                  if (!/\((.*?)\/(\s|\))/.test(x)){                                      // when the path is a folder
                    if( (!x.includes("\":ignore\"")) &&  (!x.includes("\":ignore\""))  ){
                      x = x.replace(")"," \":ignore\")")
                    }
                  }
                }  
                if (!x.includes("](/")){ //enable relative paths
                  if( (x.includes("\":ignore\"")) ||  (x.includes("\":ignore\""))  ){
                    return x.replace("](","]("+root_url+purl+"/") ;   
                  }
                  return x.replace("](","]("+purl+"/") ;   
                }else{
                  if(x.includes(":ignore")){
                    return x.replace("](","]("+root_url) ;   
                  }
                }
                return x;  //just in case
              }
            )
        return content;
  })

[SteveShaffer]

^ I tried this solution mutates and it appears to work for the first array on the page but these lines mutate purl

                  var the_arr = purl.split('/');
                  the_arr.pop();
                  purl = the_arr.join('/') ;

so subsequent relative links on the same page end up with an incorrect URL.