search

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you
https://orchid.run
GNU General Public License v3.0
513 stars 53 forks source link

Weird menu created when .md files are placed in external directory #319

Closed daudazimkhan closed 4 years ago

daudazimkhan commented 4 years ago

In summary.md, if we provide external paths to wiki pages, the resulting menu contains submenus for each ../ e.g. if our summary.md is something contains

- [Installation](../../../../../../common-doc/resources/wiki/installation.md)
- [Basic Configuration](../../../../../../common-doc/resources/wiki/configuration.md)

The output we expect is only a menu for installation and configuration but the actual output is menu

cjbrooks12 commented 4 years ago

The Wiki plugin treats all pages as relative to the summary file, and I had never even considered what would happen when pages are above the summary root. In trying a few things out for myself, I think there are a number of bugs in handling relative paths above the resource root, unfortunately.

Instead of setting the individual pages with a relative path, it would probably be better to set the entire wiki section's baseDir to the common doc root. Unfortunately, this also seems to not work having a relative path in a parent directory.

Until I can get these issues fixed, I think you'll have to just copy the files you need into your wiki.

daudazimkhan commented 4 years ago

For now I created copyCommonResources, a gradle task that copies the common stuff to project's resources. Then made the orchidBuild, orchidServe, and orchidDeploy tasks depend on the copyCommonResources task inside each project's build.gradle. I guess setting baseDir will only make sense if we have only common pages and no project specific pages.

cjbrooks12 commented 4 years ago

I've got a fix for this, will be available in a patch release shortly. Now, when those relative file paths are parsed, they will be removed and the page will set in the wiki properly. The "resolved" path of these files (and the resulting URL) will simply be the specified path with the relative segments removed. For example, ../../../../../../common-doc/resources/wiki/installation.md will create a wiki page at /common-doc/resources/wiki/installation.

cjbrooks12 commented 4 years ago

This bug has been fixed in 0.17.6.

daudazimkhan commented 4 years ago

Thanks for the fix. One more thing, don't you think it would be better if we can somehow mention the irrelevant path so that menus/submenus are not created for them? Something like the following - [Installation](../../../../../../common-doc/resources/wiki/installation.md)(common-doc/resources/wiki/) The above should create menu for installation only because if we replace the first occurrence of common-doc/resources/wiki/ in ../../../../../../common-doc/resources/wiki/installation.md, we get installation.md This one will hide the irrelevant directories. Also, if someone doesn't provide the third part i.e. common-doc/resources/wiki/, then only ../ should get ignored

cjbrooks12 commented 4 years ago

Yes, I absolutely agree with all those points. The main problem here is that the Wiki plugin is one of the oldest plugins for Orchid, and it has a lot of stuff hardcoded to using the exact file paths it finds from the summary, and generally is quite inflexible. Issue #192 comes down to the same problems as well, and for the time being it's impossible to properly address these issues without rewriting the entire plugin with these ideas in mind.

That said, doing exactly that is on the roadmap; I plan on starting that rewrite after I get 0.18.0 released.