[Feature]: Allow configuration of a base URL

[bbbonnibel]

Is your feature request related to a problem?

I host my DocMD site at a github page. So let's imagine the docs are hosted at example.github.io/project/.

DocMD however generates at localhost:3000.

This breaks all the absolute paths I might use.

If I do the following: <img src="/assets/images/example.png">, then it works locally but breaks on deployment. I have to do a first pass like this, then replace it with <img src="/project/assets/images/example.png"> before release, at which point it will be broken locally. I have to consciously revert/unrevert if I want to work on that section further with assets loaded in.

Alternately, I have to use relative paths.

This also impacts markdown links between pages, where I have to choose between [relative](../another/page) or [absolute](/section/another/page, where the latter either works locally or on deployment but not both.

Describe the solution you'd like

If I could specify a base URL of "/project" in configuration, my absolute paths would work fine. DocMD should also aim to replicate that baseURL.

Describe alternatives you've considered

DocMD could also update URLs, but I suspect that won't be safe and might hit code blocks.

[mgks]

Thank you for the detailed explanation.

You are absolutely right, we need a standard system that people are used to, while we already have a sort of solution in place (siteUrl) where you can provide your extended paths like example.github.io/project/ and it handles such scenarios well but dealing with assets in offline subdirectories can be a manual work to some extent I suppose, which isn't ideal.

Here's a live example for the working project: SWV Documentation

While we did introduced absolute paths ./ also but that is also not very intuitive to writing. I suppose we will introduce a specific base (or pathPrefix) configuration option in the next release. I even wanted to get away from the siteUrl (which seemed necessary for SEO and sitemaps) for sometime now and make it more automated, robust and ready for worst conditions.

I will look into this and make sure we have a solution that works perfectly in all kinds of environments.

Thanks for helping improve the project!

[mgks]

We now have a very early stage implementation of this feature in release 0.3.9.
https://github.com/docmd-io/docmd/releases/tag/0.3.9

You can use config.base in docmd.config.js now but it's not added to the documentation officially yet. Not closing this issue until we make sure the feature is robust.