[Enhancement] : Serve several static paths

[gigaga]

Goal

The goal of this PR is to allow to serve several static paths to be able to seperate easily the HTML elements of docsify (css, index.html, so on) with the md files folder.

For example, by using this feature, it is possible to organize our code like this:

/md
    README.md
/html
    /assets
    /plugins
    index.html
package.json

And serve it by using the following command docsify serve html,md --port 3001.

/md contains only the whole of md files without any files required by Docsify.

It is now possible to separate the real documentation resources files and the files needed by the engine Docsify.

Syntax

docsify serve html,md --port 3001

path can have several paths coma separated.

[anikethsaha]

The goal of this PR is to allow to server several static paths to be able to seperate easily, the HTML elements of docsify (css, index.html, so on) and the md files folder.

I didnt get this !! Can you elaborate this more

[gigaga]

Hello @anikethsaha I fixed my lint issues and completed the description of this PR.

Thanks :)

[anikethsaha]

the behavior of docsify will change as the links wont be the same here.

currently docsify works like this.

docs/ 
- index.html   --> /#/
- first.md  --> /#/first
- second.md --> /#/second

Now if we divide w.r.t folders like this,

/md
    README.md
/html
    /assets
    /plugins
    index.html
package.json

I have to check whether docsify will render the path like these. cause its one dir back and changed dir. So, it will surely work with alias config but I dont know without that.

I will take a look at this. Else I think this is a good enhancement

cc @trusktr @jamesgeorge007

[gigaga]

In fact, the behavior of docsify will not change. For example :

md1/ 
- index.html   --> / (loading) --> /#/ (render)
- first.md  --> /first.md (loading) --> /#/first (render)
- second.md --> /second.md (loading) --> /#/second (render)
md2/ 
- third.md --> /third.md (loading) --> /#/third (render)

The folders in path parameter will be reachable from the same "/" url, even if they are served from several folders.

[anikethsaha]

In fact, the behavior of docsify will not change. For example :

md1/ 
- index.html   --> / (loading) --> /#/ (render)
- first.md  --> /first.md (loading) --> /#/first (render)
- second.md --> /second.md (loading) --> /#/second (render)
md2/ 
- third.md --> /third.md (loading) --> /#/third (render)

The folders in path parameter will be reachable from the same "/" url, even if they are served from several folders.

I meant for the docs/index.html , not for the docs/md1/index.html Actually , the link will have to change I think if index.html is inside docs/md1 and you are making a request for docs/md2/third,md

[gigaga]

If your path is ./docs, so the index path will be docs/index.html.

If your path is ./docs1,./docs2 my code will search an index.html in docs1 and docs2. So indeed, if index.html in docs/md, path should be ./docs/md (same behavior that actually where path can have just one value).

[anikethsaha]

docs/
- index.html   --> /#/
- md/
  - first.md  --> /#/md/first
  - second.md --> /#/md/second

but

docs/
  - index.html   --> /#/
md/
  - first.md  --> ?
  - second.md --> ?

I agree, its not a breaking change but we should cover all the cases before considering this. I am actually 👍 for this feature but just discussing the possible the cases and outcomes

[gigaga]

In your example, that will be :

With path=docs,md :

docs/
  - index.html   --> /#/
md/
  - first.md  --> /#/first
  - second.md --> /#/second

But we can do it also :

With path=html,docs:

html/
  - index.html   --> /#/
docs/md/
  - first.md  --> /#/md/first
  - second.md --> /#/md/second

;)

[trusktr]

Is this totally backwards compatible with the current functionality (it behaves just like any other static server)?

[gigaga]

Yes, there will be no changes if you use a single path value. The current behavior will be remained.

[trusktr]

LGTM then.

Note, I personally am not in favor of the feature, as it diverges from standard expected static serve behavior (for example, your project's file structure (if using this new feature) may become incompatible with standard tools from NPM like serve, live-server, http-server, etc).

[gigaga]

That may be not the default behavior.

Serving static from several paths is a real need. With it, it is possible to separate the static resources by their natures.

The main tools serve the same type of resources, html files, but it is not the case for docsify where there are the files for the content (md) and the files for the presentation (html).

It is my motivation 😉

[gigaga]

Hello,

can I have some news about this PR? ;)

[trusktr]

The main tools serve the same type of resources, html files

The main tools just serve files, doesn't matter what format they are in. You could still serve markdown files from one folder, html from another, and js from another.

If I read correctly, what you want is to merge the folders together when they are served from the root / of the domain. So if I understand correctly, you want a filesystem structure like

/md
    README.md
/html
    /assets
    /plugins
    index.html

but you want to be able to load your-domain.com/README.md and you-domain.com/index.html as if they were served from the same root folder, right?

Also based on reading your comments, it seems like you want to map certain folders to certain Router paths.

Would it be better to have a runtime option that tells Docsify runtime where to look for files and how to map those to the Router paths, and leave the server as a regular static server in which actual HTTP request paths match the file-system paths?

If we can achieve what you want as a runtime option, then it means anyone can achieve the same regardless of which static server they use (in the case of the majority of static servers that simply mirror the file system structure).

[gigaga]

Hi everyone,

It is possible to have a status about this PR?

Thanks,

[anikethsaha]

hey! @gigaga ,

Just one note ! even if this CLI is serving like this

/md
    README.md   // localhost.com/README.md
/html
    /assets
    /plugins
    index.html     // localhost.com/indexhtml

This will work fine with docsify-cli but when we host the same site in some hosting service like netlify which I guess allows only one folder to serve, then it would break that. it will create an inconsistency.

[gigaga]

Hi @anikethsaha,

Probably, I don't know netlify! But it still is usable with heroku. However it is simply an optional feature, serve several paths cannot be used. For my part, we cannot be compliant with the whole of tools, cloud servers available in the world 😉.

Thanks

[anikethsaha]

I think with heroku you get a VM or container where you can customize a lot.

in heroku are you using docsify-cli to serve the content ?

[gigaga]

Yes we can. We have some freedom with this kind of services.

[hiddewie]

Is there an update on this PR?

This feature solves problems with serving Docsify with auto-reload where the directory structure is split into multiple directories per concern (source files, static files, documentation files). Especially when other libraries are bundled (using Rollup for example), the output ends up in another directory than the static/source files. It is not possible to serve Docsify documentation combined with bundling source files.

There is one workaround, which is concurrently serving two directories, using concurrently, http-server and docsify-cli (serve). For example:

concurrently \
    'docsify serve src --port 4001' \
    'http-server --proxy http://localhost:4001 -d false -i false -p 4000' dist

(the src directory would contain index.html, all the .md files. The dist folder would contain bundled .js and .css which is referenced from index.html).

[anikethsaha]

@gigaga Apologies for the delay here.

Could you just try to host a sample site in netlify or vercel` using this command? or @hiddewie even you can volunteer here to move this.

If this is working fine with it we are good to go. Other wise we need to fix that.