search

razetime / ngn-k-tutorial

An ngn/k tutorial.
https://razetime.github.io/ngn-k-tutorial/
195 stars 22 forks source link

Build EPUB + HTML and deploy to Github Pages on push #17

Closed DestyNova closed 8 months ago

DestyNova commented 8 months ago

I thought it would be nice to read these docs on Kindles and other e-readers, and after testing it locally with Pandoc, it made sense to also produce HTML and deploy it via Github Pages.

Here's what it looks like on my repo's page. Not quite as pretty as the Github Markdown viewer, but it seems to work and the table of contents links are clickable.

If you want to try merging it, Github Pages will need to be enabled for the repo (Settings -> Pages -> enable with source = Github Actions). Let me know if there's any problems -- I had to try a bunch of things to get the CI bit working, and squashed my commits to hide the shame.

razetime commented 8 months ago

Thank you for the patch. I intended to use MdBook at some point but this looks much cleaner. I also see some glaring issues with my titles here, so that is nice to spot.

I don't see an epub in this pull request. I assume it will be added automatically when the action runs. I'd like to provide a pdf as well, so I'll add that workflow to the patch and then do a proper merge.

DestyNova commented 8 months ago

Thank you for the patch. I intended to use MdBook at some point but this looks much cleaner. I also see some glaring issues with my titles here, so that is nice to spot.

I don't see an epub in this pull request. I assume it will be added automatically when the action runs. I'd like to provide a pdf as well, so I'll add that workflow to the patch and then do a proper merge.

Yep the action generates the EPUB, so we don't need to add it to the repo direct. PDF would be nice too -- I tried it out earlier and something was off (can't remember what) but it's probably not a hard fix. Apart from some slight inconsistency in the chapter titles, it might be nice to expand the Pandoc metadata a little since it's just title and author atm.

DestyNova commented 8 months ago

Hmm, I just took a look at mdBook and its HTML output is much nicer looking. It has dark mode and the TOC stays visible in a frame on the left. Maybe this could use mdBook for the HTML on Github Pages and keep Pandoc for generating the EPUB (since mdBook doesn't have support for that yet)?

razetime commented 8 months ago

I looked at the pandoc docs and added a pdf workflow. Don't know when the workflow will run, maybe you have to approve it to check.

razetime commented 8 months ago

also regarding the mdBook part I think this pandoc workflow suits a K book well. It might be better for readers though, so if you think that's best I will replace the html build with that.

razetime commented 8 months ago

ok, the page is ready with a pdf and epub. For now this will be merged in its current state.

DestyNova commented 8 months ago

Nicely done @razetime -- the PDF version looks great now too!