search

orchidhq / Orchid

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

Base URL has beginning `/` stripped #264

Closed drewsilcock closed 5 years ago

drewsilcock commented 5 years ago

I'm experiencing an issue related to #260 - I would like to have my Orchid generated documentation in a sub-directory of my overall documentation, in this case at example.com/backend/..., so I set the baseUrl to /backend/. However, the generated code has /backend/ replaced with backend so that links to files end up as backend/file.css (for example) instead of /backend/file.css.

Thanks in advance!

Info

Version: 0.16.9

Screenshot demonstrating HTML output: image

Log of Orchid build: Orchid Build.log

cjbrooks12 commented 5 years ago

Orchid was really designed to use full http://... URLs for the base URL, for a number of reasons. Given that you know it should be in a subdirectory when deployed, is there a reason why you don't just use the full URL it will served on?

Just for context, here are a couple of the reasons why Orchid expects a full URL, and why you might want to use one as well:

1) it makes it easier to format URLs throughout, both under-the-hood and also at the user-level within templates 2) it's better for SEO, search engines like having full HTTP URLs to work with 3) It becomes possible to simply find-and-replace that base URL on every page when deploying, so there's a possibility to build the site once and deploy it at multiple URLs without needing them to be in the same subdirectory. Replacing just part of a path will likely be too aggressive and may cause some broken links. 4) Orchid has ways to link to other Orchid sites, such as with the Javadoc plugin linking to external classes. If those other sites use a relative base URL, then those external links end up looking like internal links, which is incorrect.

drewsilcock commented 5 years ago

The reason is that the documentation isn't going to be hosted in one central location but bundled as generated HTML with some other documentation and distributed as a self-contained zip so that anyone can pick it up and view it.

As it's private documentation for private code that won't be hosted on any central publically available site things like SEO don't matter.

cjbrooks12 commented 5 years ago

I see, that makes sense. I'll get a fix out for this in the next couple of days.

cjbrooks12 commented 5 years ago

This has been fixed in 0.16.10. Check it out and let me know if you have any further issues!

drewsilcock commented 5 years ago

Just upgraded, all working perfectly now, thanks again!