Custom content for Github Pages index.html

[CxRes]

This is more of an enquiry rather than an issue:

Is it possible to override the index.html page generated in gh-pages branch? I would rather it display the Readme (or something else) and augment that with the generated links.

[martinthomson]

It should be possible to integrate other material into an index page (or even move the index page to a different page and use different content for the index), but that would require some work. I'm happy to leave this issue open in case someone wants to do that work (I don't have spare capacity right now, even though this would be relatively straightforward).

[CxRes]

Can you point me to where this code lives?

[martinthomson]

There is code in the README generator (https://github.com/martinthomson/i-d-template/blob/main/setup-readme.sh), but the main code is here:

i-d-template/ghpages.mk

Lines 78 to 86 in eb41d49

	GHPAGES_ALL := $(GHPAGES_INSTALLED) $(GHPAGES_TARGET)/index.$(INDEX_FORMAT)
	$(GHPAGES_TARGET)/index.$(INDEX_FORMAT): $(GHPAGES_INSTALLED) $(DEPS_FILES)
	$(LIBDIR)/build-index.sh $(INDEX_FORMAT) "$(dir $@)" "$(SOURCE_BRANCH)" "$(GITHUB_HOST)" "$(GITHUB_USER)" "$(GITHUB_REPO)" $(drafts_source) >$@
	ifneq ($(GHPAGES_TARGET),$(GHPAGES_ROOT))
	GHPAGES_ALL += $(GHPAGES_ROOT)/index.$(INDEX_FORMAT)
	$(GHPAGES_ROOT)/index.$(INDEX_FORMAT): $(GHPAGES_INSTALLED) $(DEPS_FILES)
	$(LIBDIR)/build-index.sh $(INDEX_FORMAT) "$(dir $@)" "$(DEFAULT_BRANCH)" "$(GITHUB_HOST)" "$(GITHUB_USER)" "$(GITHUB_REPO)" $(drafts_source) >$@
	endif

[CxRes]

Thanks for that!

What I am wondering is why are you even bothering to create a separate index.html page? The Readme is already much nicer for the most part and if you copy it to gh-pages branch (add-in the issues link if you like) GitHub Pages will happily deploy it (it wants index.html, index.md or README.md). Also makes for a simpler script!

I don't speak bash well, otherwise I would have PRed it myself.

[MikeBishop]

The README contains only the main branch for each document, whereas the index.html will give you the .txt/.html/compare links for each draft in the repo for each recently-used branch. Very handy when you have a lot of PRs flying in all directions from various editors; matters less in a single-draft single-editor repo.

Simple example:

[CxRes]

Well, you can copy the readme and generate this extra stuff if you want. It will still be simpler to write the markdown than generating the HTML (using shell script, impressive!). That way you can have a nice landing page and all this stuff. And you could also then perhaps configure Jekyll templates.

What I am really after is to have a landing page where I can introduce what I am doing (for the price of free :P).

[martinthomson]

The HTTP working group uses markdown for this index (it's a supported option). They manage the landing page problem by having a separate github.io/foo page for that.

[CxRes]

I looked into HTTPWG repos. They are using index markdown for the HTTP extensions page, with the rest of everything being served from <httpwg.github.io> repo as you describe. But it is unclear to me how to configure i-d-template so that index.md is generated and index.html is suppressed (the only benefit of doing this is the md page render with a template (of the parent in case of HTTPWG site, how?) and looks a tad nicer).

@martinthomson Can you please point me to the configuration that enables the index.md and suppresses index.html? I tried to manually copy stuff over, but that gets deleted on a subsequent push!

[martinthomson]

https://github.com/httpwg/http-extensions/blob/main/Makefile#L3 sets INDEX_FORMAT. I don't know how that is being styled, but I think that it requires that you understand how to use Jekyll (and I don't).

[CxRes]

Thanks! I'll play around tomorrow to see how far I can get.

I don't have much knowledge about Jekyll but I believe the default is to style using the Primer template https://github.com/pages-themes/primer. You can provide your /_layouts/default.html to override the template. In case of HTTPWG that is being overridden by https://github.com/httpwg/theme in https://github.com/httpwg/httpwg.github.io/blob/main/_config.yml

(The mystery for me is how HTML extensions inherits HTMLWG template with nothing defined in that repo; then I don't know much of how Github Pages work).