Adding file not from `docs` folder

[iakovmarkov]

Hey guys.

Thank you for this nice tool. I've tried to use it in our projects and found one thing that I'm probably missing.

Our docs are located close to the code itself, like ./src/modules/resources/README.md. I want to include this file in a sidebar like this * [Resources](../src/modules/resources/README.md), but it doesn't work - I'm getting 404 on that page. I've tried to play with path config variable, but it feels it has 0 effect on anything.

Is there any way to do this in current version of docsify? If not, is this something am I welcome to implement?

Cheers!

[SidVal]

Can you tell us your repo's url please @iakovmarkov ?

Btw, I read it again, and you must move the "content" to your docsify folder.
I think docsify can't read other "md" from outside.

[iakovmarkov]

@SidVal it's a private repo on our on-prem bitbucket with a production application, so I can't, sorry :)

I think docsify can't read other "md" from outside.

Yea, I also think that's the case. I feel it is something that is worth implementing. I can start working on that if @QingWei-Li is OK with it.

[QingWei-Li]

If you want to do this, you must use absolute path.

[iakovmarkov]

If you want to do this, you must use absolute path.

This is practically impossible, right? Using abs paths in .md files will work only in case where every developer's environment/folder structure has been set up in the same way.

[kjantzer]

@iakovmarkov Any progress on this? We also store most of the .md docs along with the code (outside of the /docs dir)

[iakovmarkov]

@kjantzer I actually ended up using a little workaround:

• Set up a index.html file in the root of the project
  • Load Docsify from CDN in it: <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  • Configure Docsify: <script>window.$docsify = { ... }</script>
• Install a tiny HTTP server lib: npm i -D http-server
• Set up a NPM script to spin it up on port 8084: "docs": "http-server './' -p 8084"
• Done!

Running npm run docs now gives me a Docsify instance on port 8084. Since I'm using project root dir as a web server root dir, I can reference files from it by relative path in sidebars (or everywhere really): [Autocomplete](src/one-ui-core/containers/Autocomplete/README.md)

[timaschew]

If you want to deploy that somewhere you anyway need to filter for md files. You probably don't want to make everything in your src/ directory public.
So if you anyway will have a list of external md files, I personally prefer to copy them to the docsify directory rather than running docsify in the project root.

[trusktr]

Hey you all, using symlinks works fine. In your docs folder:

cd ./docs
ln -s ../src

creates a linked src folder in your docs folder. Then in any markdown file, you can reference files like src/modules/resources/README.md.

Expanding on @timaschew's idea, you could also make a build step to copy src (only markdown files) into the docs folder. You could use gulp or grunt for this.

Another idea is to configure your static HTTP server not to serve certain files (after linking src f.e.)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[onexdata]

This is a really useful feature for self-documenting your source code, or adding snippets or embeds from non-public stuff that you want to partially expose.

Probably 20% of people that use docsify would use this, they just don't know how close docsify is to being able to implement it... I mean when I read you allow includes and fragments already I was shocked this feature didn't exist.

With the existing code fragments and includes, this literally lets you point to your source code and drop pieces anywhere...

For example, this works, but you have to expose your entire source code to the public...
[filename](embed.js ':include :type=code :fragment=demo')

Where as, if you allowed a proxy, mapping in a folder, or simply allowed relative paths, the code could be kept private...
[filename](../src/embed.js ':include :type=code :fragment=demo')
...or...
[filename](embed.js ':include :type=code :fragment=demo :path=../src')

[trusktr]

Hello @onexdata! What are you proposing exactly?

Relative paths won't work if the static server is not able to serve those files.

Where as, if you allowed a proxy, mapping in a folder, or simply allowed relative paths

What's the idea here? I don't see why not to allow relative paths there if that's something not yet supported (PRs welcome!), but I don't see how that solves the server issues.

[ajs139]

It'd be possible to scan all the docs files, and copy across any referenced file that exists in the source files into the docs folder. This works well if the file is linked using a root-relative link, e.g. /src/some/file.js. Doing this will mean the link is clickable when rendered by GitHub's markdown renderer, pointing to the actual source file.

example gist - https://gist.github.com/ajs139/659ce8b37f5ab1c112d1b59ab6c66013

If doing this, it's probably worth adding the source directories (e.g. docs/src) to the .gitignore file.