Set up github pages

[JayPanoz]

Short description of the issue/suggestion:

We have a lot of docs in markdown form that could be published almost AS-IS, similar to what’s being done on https://github.com/readium/architecture.

What is the expected behaviour?

Docs + intro (ReadMe) available as a website i.e. readium.github.io/readium-css

What is the current behaviour?

You have to take a deep dive into the master branch to find the doc.

What is the motivation / use case for changing the behaviour?

It would be a lot more readable and easier to access.

Other information (e.g. related issues, suggestions how to fix, links for us to have context)

Beware navigation across docs and links I guess.

[JayPanoz]

I guess there’s no way to have Previous/Next Doc linked at the bottom of every markdown file unless we “hardcode” that in the md, @HadrienGardeur?

We’ve been using the md files to generate an EPUB file so far… consequently, it would have to be removed if we keep on providing this EPUB file.

[HadrienGardeur]

@JayPanoz this feels a lot like a discussion about Web Publications 😇

There's indeed no automatic way to have previous/next doc links by default (there's no such concept on the Web or on Github). You'd have to manually add them and I guess hide them using CSS in the generated EPUB file.

If you'd like to get even more experimental, you could also go full WP on these pages and include a manifest + JS to generate such navigation.

[JayPanoz]

Well after some additional research, GitHub would probably answer this is what Jekyll is for, indeed.

I’ll check what the most sustainable option could be.

[llemeurfr]

Yes, Jekyll is the way to go. But it means moving the readium-css pages to the github.io repo IMO. We tried other ways (reference, inclusion) which were not practical.

[HadrienGardeur]

@llemeurfr you've missed the last two calls I think and during the first one, I actually started using the same Markdown files in architecture for the repo and the website at the same time: https://readium.org/architecture

IMO it is much better to avoid duplicating the effort of presenting these projects than forcing ourselves to use a separate repo just for the sake of keeping the design consistent with the same header/footer.

[JayPanoz]

Clarification: Jekyll’s running behind the scenes anyway, no? Only does it treat assets (.md files) as static when creating github pages as far as I can understand.

So I was wondering if you could say use include without generating all the files it needs (i.e. overriding the hidden Github’s ones). That said, it won’t help with EPUB conversion but I can now remember I had to do some manual edits anyway…

[JayPanoz]

So yes it’s using Jekyll Default Layout, cf.

• Publishing with GitHub Pages, now as easy as 1, 2, 3
• Getting Started with GitHub Pages
• Where does the head section come from when github pages generates source?

[JayPanoz]

Alright got the default github-pages config running locally by following those instructions.

Since I didn’t want to add this repo as origin yet, the trick is to create a _config.yaml file with repository: <usr>/<local-repo-name> so that bundle exec jekyll serve can run and serve the pages @ localhost:4000.

It’s my understanding everything is generated as static assets in a _site folder, cf.

Note there’s only a CSS file added as an asset, no JS, nothing.

I’ll try adding some stuff to see if you can build on top of the default config.

[JayPanoz]

Looks like you can so I’ll give it a deeper look next week.

There’s probably a way to handle that using templates so that includes don’t pollute markdown.

[JayPanoz]

Unless I’m missing something, which is quite possible given the amount of commits I’ve just made to correct paths and stuff, master/docs must not follow the repository naming scheme \<username>.github.io or \<orgname>.github.io.

Problem is it automatically does when switching to master/docs as the source of github pages and will look for a CNAME in this folder.

So I added a link in the ReadMe + an index in the docs folder with a TOC.

[JayPanoz]

BTW @llemeurfr, as quickly discussed with Hadrien through Slack, there may be a possibility to have the Readium.org layout/theme on all subdomain/project pages but that implies to make it a theme available as a gem so that project pages can reference it in the Jekyll config – or alternatively a repo on its own but I’m really not sure about this option.

[JayPanoz]

Setup done so an hypothetical update should be another issue.