Explicitly set baseurl in _config.yml, README docs

[markwkidd]

I have been learning Jekyll and Just the Docs recently, thank you for this very helpful template. Based on my experience customizing Just the Docs, my intention with this PR is to bring the Just the Docs README and default configuration closer to the approach recommended by Jekyll.

If I understand Jekyll correctly, when a site is going to be served from a subfolder, the baseurl parameter should be set in _config.yml. Jekyll resources often specifically name a Github Pages deployment as an example of a situation when baseurl should be used.

So if I have a github repo named cushaw-handbook that I am deploying via Github Pages, I believe that the correct Jekyll configuration would include:

url: https://markwkidd.github.io
baseurl: cushaw-handbook

In my situation this is relevant to image processing and styling. With baseurl set, I can now use functionality Jekyll's relative_url function in my content:

![Drying seeds removed from fruit]( {{ '/assets/images/recipes/cut-fruit-with-seeds.jpg' | relative_url }} )

Thank you for considering this patch.

[janbrasna]

This has been here before: 1ea731f — and the comment "… the action renders this unnecessary" sheds some light on it. You're right it's the correct configuration, however it's most likely being set up dynamically by the publishing action here:

just-the-docs-template/.github/workflows/pages.yml

Lines 40 to 43 in 8406f5c

	- name: Setup Pages
	id: pages
	uses: actions/configure-pages@v5
	- name: Build with Jekyll

It's not exactly documented well but actions/configure-pages does a lot of this magic happen based on the running context.

[markwkidd]

Thank you for your reply.

I have installed this template twice in the last few months, and the automated workflow did not set this up automatically. I had to investigate the source of the issues I was having with some paths and edit this line in manually.

I have just used the template to generate a third new repository. This is the _config.yml file: https://github.com/markwkidd/test-the-docs/blob/main/_config.yml

As far as I can tell, it does not include the baseurl line I am suggesting here. To have that feature work correctly, I would need to understand the issue and research an answer. Is it possible I am either misunderstanding, or the logic you describe isn't being applied to this situation?

[janbrasna]

You won't see it in the actual file. What @actions/configure-pages does is when run it "prepares" the config according to the repo it's run from right at build time. However, looking at the source, I can see Gatsby being referenced, but not Jekyll: https://github.com/actions/configure-pages/blob/d5606572c479bee637007364c6b4800ac4fc8573/action.yml#L11 which does indeed seem weird.

[markwkidd]

When would that line be added to a config.yml generated by the template? I am confused by your comment that the baseurl line would not be visible once the template has been generated and the Jekyll scripts are being processed in the new repository.

To try to put this another way: I have generated a repo using the template, and configured GitHub Pages to run the Just the Docs scripts. At this time, the needed baseurl line is not appearing in the generated config.yml I linked to. It seems to me I am at the last step of a deployment, and if any scripting was going to add the necessary baseurl line, it would have happened by now.

[janbrasna]

Ah, right, they don't write config at runtime, they return the path in step outputs, to be passed as a parameter later. Here:

just-the-docs-template/.github/workflows/pages.yml

Lines 40 to 45 in 8406f5c

	- name: Setup Pages
	id: pages
	uses: actions/configure-pages@v5
	- name: Build with Jekyll
	# Outputs to the './_site' directory by default
	run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"

what actions/configure-pages does is that it gets the correct base_path for the repo, and passes it to the build CLI as --baseurl — that should be equivalent to having it explicitly in the config anyways. (If that's not the case for all functionality, it may be possible to be a bug in Jekyll. And actually not writing the config is a gap in the action itself, I will probably report that anyways.)

[markwkidd]

I have deployed this template three times including the recent test I linked to. In none of those cases did this functionality work automatically. I would be glad to submit more information or do more testing if it is helpful.

[janbrasna]

The "recent test" has no content, thus no links to check. I did clone the handbook repo mentioned in the description tho, made completely bogus config changes, deployed it at a relative baseurl at GitHub.io, and all links work, as the build workflow logs show the paths get set correctly:

• janbrasna/jekyll-jtd-conf-test@d68066c
• https://github.com/janbrasna/jekyll-jtd-conf-test/actions/runs/12860977277/job/35853681383#step:5:2
• https://janbrasna.github.io/jekyll-jtd-conf-test/

Unless you're describing a surface or a plugin functionality not obviously visible from the few main pages, in that case please try to explain a bit more; however I seem to have relative links to pages and images apparently working, unrelated to what's in the boilerplate config.

[mattxwang]

Hi folks,

Thanks for the lively conversation! Apologies for the delayed response - have been super busy with work.

Broadly speaking, completely agree that the current iteration of the template excluding baseurl can be confusing, both for the reason that @markwkidd mentioned above and because many other tutorials and themes will make an explicit mention to it.

I should also note that the default value for baseurl is "" (see: Jekyll's Default Configuration), which makes this potentially more confusing for users.

My only concern (that prevents me from just hitting "merge" on this PR right now) is making sure that explicitly setting baseurl: '' (like in this diff) doesn't break https://just-the-docs.github.io/just-the-docs-template/ itself (which, if I recall correctly, was my motivation for 1ea731f - avoiding confusion for folks who directly use this theme's _config.yml). I can try to set aside some time to look at this more in-depth this weekend (while simultaneously avoiding pushing to prod). Separately, I might suggest a minor docs improvement as baseurl is a frequently misunderstood Jekyll feature.

Thanks for your patience!