Document how to customize page

[rgaiacs]

Closes #1907

We might want to make add a new traitlets for users to provide their own Jinja template that will be used in

binderhub/binderhub/main.py

Line 42 in 4f0a91a

"page.html",

from

binderhub/binderhub/main.py

Lines 41 to 46 in 4f0a91a

	self.render_template(
	"page.html",
	page_config=self.page_config,
	extra_footer_scripts=self.settings["extra_footer_scripts"],
	opengraph_title=self.opengraph_title,
	)

[manics]

There's something wrong with the link syntax- it's not linked:
https://binderhub--1923.org.readthedocs.build/en/1923/customizing.html#header-and-footer-customization

[manics]

I think it'd be helpful to also highlight the important parts of the template- is <div id="root"></div> the critical bit?

[manics]

Is additional Helm configuration needed to mount the file in the ConfigMap into the BinderHub pod?

[rgaiacs]

I will address the comments in a couple of weeks.

[rgaiacs]

Sorry for the delay to return to this.

I address the comments.

Do I need to add some tests? If yes, can I have some help? Thanks!

[agahkarakuzu]

@rgaiacs thanks for this PR!

How complicated would it be to customize components like HowItWorks.jsx, and have the template page use the built dist to control what gets rendered inside <div id="root"></div>?

For example, I can easily add header/footer

but I cannot figure out a way to "replace" the binder logo with this design.

Also, I think extra_static_path no longer takes effect, or at least I could not figure out how to link assets I used to mount at /etc/binderhub/custom/static.

[rgaiacs]

Hi @agahkarakuzu,

the challenge to customise any file in binderhub/static/js is due to how the JavaScript works.

We are using webpack to merge all JavaScript files into a single bundle.js file that is we reference in the HTML that we send to the user, see

binderhub/binderhub/templates/page.html

Line 27 in 837169d

<script src="{{static_url("dist/bundle.js")}}"></script>

How complicated would it be to customize components like HowItWorks.jsx

If you want to change any of the JavaScript files, for example HowItWorks.jsx, you will have to

1. re-run webpack to create a new bundle.js.
2. create a new volume that overwrite the default bundle.js with the one that you created.

[agahkarakuzu]

Thanks @rgaiacs ! I actually created a new bundle.js. Would simply mounting the new distribution override the existing one?

[rgaiacs]

Would simply mounting the new distribution override the existing one?

It should.

[agahkarakuzu]

It did! https://binder.evidencepub.io

  - name: custom-templates
    mountPath: /usr/local/lib/python3.13/site-packages/binderhub/static/
    subPath: static

The mountPath is a bit dependent on the python version, but I was able to build the sources from modified content and have that content rendered.

Build sources are from https://github.com/evidencepub/binder-template/tree/preview. I'll add a github action to this repository to better streamline the builds.