Implement --baseUrl option for the deploy command

[lhw-1]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

#534 and #2218

What is the area that this feature belongs to?

Author Usability, CLI

Is your feature request related to a problem? Please describe.

We can consider implementing a --baseUrl option for the deploy command (same as the --baseUrl option for the build command).

We want this because a custom baseUrl is necessary for the GitHub and Netlify deployments to work. Here, baseUrl must be set as the repository name, as per User Guide - Deploying the Site section.

This implementation will make the deployment process with a custom baseUrl more straightforward.

Describe the solution you'd like

There is a --baseUrl option available for the build command.

The deploy command currently runs the build command before deploying (changes introduced in #2218), but does not have access to this feature. We can introduce this option to the deploy command similar to how it is done for the build command.

As always, suggestions for / criticisms of the idea are welcome!

Details on previous issue

Currently, when deploying a MarkBind site from a git repository, the user will run markbind init (with or without --convert as needed) to initialize the MarkBind site, and run markbind deploy to generate and deploy the site to GitHub pages. However, the user must also specify the baseUrl property in site.json to be the name of the git repository for the deployment to be successful without issues, as the deployment will default to an empty baseUrl property. This behavior is documented here as a necessary step.

From a user's standpoint, if they are doing a quick deployment from a git repository to a MarkBind site, adding the baseUrl property is a bit of a hassle. Note that this is the same level of convenience as not needing to call markbind build before deployment, since the user can simply use the --baseUrl property, and once #2249 has been resolved, this can be done with the deploy command itself. Essentially, this is a non-urgent, nice-to-have feature.

Hence, I would like to discuss the possibility and feasibility of extracting the name of the git repository, potentially from the directory name or from the .git subdirectory, in order to use it as the default baseUrl if we can detect that it is a git repository.

On one hand, this will be useful since:
- The deployment steps will only consist of markbind commands: markbind init and then markbind deploy (#2218 has made markbind build an optional step).
- User will not have to remember to specify the baseUrl for straightforward deployments.
- Most users will likely be converting from an existing git repository to MarkBind.

On the other hand, this could also be considered too much hassle compared to the benefits it offers.

Describe alternatives you've considered

No response

Additional context

No response

[ang-zeyu]

from a git repository

Do you mean To a GitHub repository? (GitHub pages specifically?)

Asking because having a git repository does not mean you are using a hosting service where baseUrl = repo name of your code hosting service.

[lhw-1]

Right, that wasn't clear - I meant "generating baseUrl from a git repository" and deploying to GitHub pages and netlify. Currently, the baseUrl property is needed when deploying to GitHub pages and netlify, so auto-generation of the baseUrl during deployment would be quite convenient.

From what I can tell, the baseUrl property is not necessary for other deployments, but I am concerned that having an auto-generated baseUrl could interfere with the deployment process for other platforms (e.g. Travis CI, Circle CI, etc.).

[ang-zeyu]

As always, suggestions for / criticisms of the idea are welcome!

I see, I think we should not implement this in that case for a few reasons:

• baseUrl configuration is a very common thing in SSGs. Having defaults in some situations makes the operation less transparent.
• Configuring GH pages / netlify with a CNAME is very common. We can probably detect this, but at that point I'd wonder if it be worth it.
• As you mentioned, a CLI --baseUrl option should make this even more convenient.

@damithc probably has a more informed opinion here as he's probably configured many more static sites.

[damithc]

@damithc probably has a more informed opinion here as he's probably configured many more static sites.

Compared to the effort that goes into creating the site content, the effort needed to set the baseUrl in site.json is negligible. So, this feature might not matter to serious or long-term users. But it might make a more notable difference (especially, on the 'ease of use' front) to a new user trying out a toy website to see how MarkBind works. Still, we need to compare the cost of maintaining the extra code of this feature to the benefit.

[lhw-1]

I see, in that case we can forgo the proposed automatic baseUrl generation since it does seem to result in more hassle than it's worth.

I realize that we have no --baseUrl property for the deploy command - it should be relatively straightforward to implement this by copying how we are doing it with the build command currently. This should at least make the deploy process with a custom baseUrl (as it is needed for GitHub and Netlify deployments) more straightforward.

I'll change the issue to reflect this 👍

EDIT:

To add on, when implementing the --baseUrl option for the deploy command, we should properly handle custom baseUrl when --no-build option is specified.

Suppose that we implement a --baseUrl option. If the user has previously built the site with a custom baseUrl and then deploys the site, i.e.

markbind build --baseUrl /myrepository
markbind deploy --no-build

This is a potential use case, and doing this should not overwrite the baseUrl with an empty string.