ePub build

[mgarciaisaia]

I'd love to have an ePub version of the guide. I understand it's a hands-on guide, but being able to read it on the go and then practice at home would be nice.

[Mte90]

I agree also a PDF and don't forget to add a license to the project.
As I prefer to read in paper so I was thinking to printing for my own usage but is not clear.

[bellesea]

I'd love to have an ePub version of the guide. I understand it's a hands-on guide, but being able to read it on the go and then practice at home would be nice.

ooo that's a great idea! thank you hehe :) i think we'll wait a month or so for the amazing open source community to help strengthen the guide and we'll look into converting it into an epub/pdf version. if anyone is willing to take this on, we'd also really appreciate it!

[bellesea]

I agree also a PDF and don't forget to add a license to the project. As I prefer to read in paper so I was thinking to printing for my own usage but is not clear.

hii :))

on creating a PDF version: we hope to create it in a month or so but if you do create it before then, we'd love for you to share it w/ everyone else here hehe! if you make a PR, we can add a link to download in the guide (and attribute you appropriately). thank you :)

on licence: thanks for the reminder! we'll add it :)) also, yes you can print it for your own usage (or even share with other people so long there's attribution).

All of Hack Club's content is released under the Creative Commons Attribution-ShareAlike 4.0 International license. All code is released under the MIT License. For the license's full text and attributions, please see LICENSE.

source: https://github.com/hackclub/hackclub

[m3rcurial]

I'd love to have an ePub version of the guide. I understand it's a hands-on guide, but being able to read it on the go and then practice at home would be nice.

ooo that's a great idea! thank you hehe :) i think we'll wait a month or so for the amazing open source community to help strengthen the guide and we'll look into converting it into an epub/pdf version. if anyone is willing to take this on, we'd also really appreciate it!

I wouldn't mind giving this a shot! I'll make a branch on my fork and try to see if I can convert them to epub and then maybe make a script or something to automate it when new commits are pushed.

[m3rcurial]

https://github.com/pandoc/pandoc-action-example
https://pandoc.org/MANUAL.html

Pandoc looks really slick but instead of doing it all manually, your team might benefit from adding it into Github Actions so it can always be up to date when changes are merged in! That way there aren't issues with updates making it out of sync.

As much as I'd love to learn Github Actions, I'm not sure if I can make them in my fork and merge them over to yours. I could, on the other hand, get it working on my fork and then communicate to the team what to do to implement it if you want? Just let me know!

[mgarciaisaia]

I can try setting up an Action if you come up with the right commands to build the books.

[bellesea]

hii @m3rcurial omg if you can get it working and share instructions on how to replicate it, that would be AMAZING! thank you so so much!

[bellesea]

hey @m3rcurial hope you're doing incredible! any updates on this? if not, no worries at all hehe :) thank you SO MUCH for your help :)

[m3rcurial]

hey @m3rcurial hope you're doing incredible! any updates on this? if not, no worries at all hehe :) thank you SO MUCH for your help :)

Work has really picked up for me so I had to put this on the backburner!!

But I was able to get a Github action to convert the markdown file into epub, where I ran into issue(s) was stitching the files together in a way that was....actually good haha. It looked like one thing I would have to consider is changing the folder structure / layout of how the files are stored in the repo, OR get fancy with some scripting (not my strong suite but we can learn!) and do something with that.

Either way I plan on trying to get back to this hopefully in the next week or two!

[bellesea]

hey @m3rcurial hope you're doing incredible! any updates on this? if not, no worries at all hehe :) thank you SO MUCH for your help :)

Work has really picked up for me so I had to put this on the backburner!!

But I was able to get a Github action to convert the markdown file into epub, where I ran into issue(s) was stitching the files together in a way that was....actually good haha. It looked like one thing I would have to consider is changing the folder structure / layout of how the files are stored in the repo, OR get fancy with some scripting (not my strong suite but we can learn!) and do something with that.

Either way I plan on trying to get back to this hopefully in the next week or two!

@m3rcurial ahh that's completely understandable haha, hope it's going well? oooo that's pretty cool, if there's anything I can do on my end to help, please let me know! I'd be happy to work on this together :) Thank you so much!

[m3rcurial]

So here is the main.yml file I made for a GitHub action.

This does make some output of an epub and pdf, but I was not able to (currently at least) get something working to verify that epub file.

Basically it's in a state where it just needs to be fed the proper order of files and how to link them with a Table of Contents of sorts (depending on how complex you want the output to be that is).

My understanding is you'd just have to add an action to the repository, then you could copy this yml content in there. It should run any time things are pushed into main (by y'all) or a pull_request is accepted (by community). If you want to have separate branches you can modify that as well.

It uses pandoc core for epub and pandoc latex for PDF. All the versions that I was using are just what I had working at the time, they could probably be updated if needed (or modified completely if there's a better way).

Overall I'd still like to come back to this at some point but I have really struggled to find the spare time for it (serious apologies for delays on even posting what I'd done so far!!).

# This is a basic workflow to help you get started with Actions

name: pandoc-convert-md

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # Job to convert from Github flavored markdown (GFM) to ePub
  convert:
    # The type of runner that the job will run on
    runs-on: ubuntu-22.04

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3
      
      - name: create file list
        id: files_list
        run: |
          mkdir output  # create output dir
          # this will also include README.md
          # echo "::set-output name=files::$(printf '"%s" ' *.md)"
          echo "::set-output name=files::$(find . -name "*.md" -type f)"

      - uses: docker://pandoc/core:2.18
        with:
          args: -f gfm -t epub --output=output/some-assembly-required.epub ${{ steps.files_list.outputs.files }}
          
      - uses: docker://pandoc/latex:2.18
        with:
          args: --output=output/some-assembly-required.pdf ${{ steps.files_list.outputs.files }}
          
      - uses: actions/upload-artifact@master
        with:
          name: output
          path: output

[bellesea]

@m3rcurial thank you so much!! no worries at all — that's fully understandable and your contribution is very valued! i just tried it out on my fork — this is awesome!! i'd love to try building on this; do you have suggestions/advice on how to iterate through the folders to feed it all the files within? thank you!

So here is the main.yml file I made for a GitHub action.

This does make some output of an epub and pdf, but I was not able to (currently at least) get something working to verify that epub file.

Basically it's in a state where it just needs to be fed the proper order of files and how to link them with a Table of Contents of sorts (depending on how complex you want the output to be that is).

My understanding is you'd just have to add an action to the repository, then you could copy this yml content in there. It should run any time things are pushed into main (by y'all) or a pull_request is accepted (by community). If you want to have separate branches you can modify that as well.

It uses pandoc core for epub and pandoc latex for PDF. All the versions that I was using are just what I had working at the time, they could probably be updated if needed (or modified completely if there's a better way).

Overall I'd still like to come back to this at some point but I have really struggled to find the spare time for it (serious apologies for delays on even posting what I'd done so far!!).

# This is a basic workflow to help you get started with Actions

name: pandoc-convert-md

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # Job to convert from Github flavored markdown (GFM) to ePub
  convert:
    # The type of runner that the job will run on
    runs-on: ubuntu-22.04

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3
      
      - name: create file list
        id: files_list
        run: |
          mkdir output  # create output dir
          # this will also include README.md
          # echo "::set-output name=files::$(printf '"%s" ' *.md)"
          echo "::set-output name=files::$(find . -name "*.md" -type f)"

      - uses: docker://pandoc/core:2.18
        with:
          args: -f gfm -t epub --output=output/some-assembly-required.epub ${{ steps.files_list.outputs.files }}
          
      - uses: docker://pandoc/latex:2.18
        with:
          args: --output=output/some-assembly-required.pdf ${{ steps.files_list.outputs.files }}
          
      - uses: actions/upload-artifact@master
        with:
          name: output
          path: output

[m3rcurial]

@bellesea I think what I would suggest is some shell wizardry with that echo "::set-output name=files::$(find . -name "*.md: -type f)" because all that's really doing right now is just running the find shell command to find all .md files in the top directory of the repository. There has got to be a way to chain some commands together, or simply do it multiple times to add onto that files "variable" that goes back to the files_list.

One solution I can think of, that would look so ugly and 100% could be optimized, would be to do find && cd to different directory && find && cd && find && cd , etc. etc. until we've gone through all of the folders in the proper order. That being said, the moment y'all add a new folder that command would need refactored, which would just be painful. But this might be enough for a proof of concept to make sure we can build in the proper order at least.