Impove accessibility and make the book downloadable as PDF document

Question

Impove accessibility and make the book downloadable as PDF document

opeolluwa opened this issue 2 years ago · 28 comments

Integrate MDbook to optimize the document navigation and make it downloadable as a PDF document
Include a workflow to build the book on updates and fixes

Answer 1 · 2023-01-03T06:47:19.000Z

You are fantastic. Thank you for getting involved. I'll sort this side of the project out soon so issues and PRs can be adequately managed with GitHub Actions. 🙇‍♂️🌟

Answer 2 · 2023-01-06T06:26:27.000Z

Have you implemented this before? Would you be able to create a branch and show me how it is installed? If not I can look at it over the weekend. I'll read the PDF that you emailed tonight too.

Answer 3 · 2023-01-06T08:04:14.000Z

I've implemented it before

Answer 4 · 2023-01-06T08:40:28.000Z

Have you implemented this before? Would you be able to create a branch and show me how it is installed? If not I can look at it over the weekend. I'll read the PDF that you emailed tonight too.

I will also create a branch to explain how to set up the in a development environment

Answer 5 · 2023-01-06T15:28:25.000Z

Thank you.

Answer 6 · 2023-01-13T13:39:25.000Z

mdbook is a binary, is there any way it can be implemented into a Git repo without me having to write my own Action? If not I can look for something else.

Answer 7 · 2023-01-13T13:55:49.000Z

A GitHub action can be implemented to build the pages and push it to gh-branch, I'll send a sample

Answer 8 · 2023-01-15T23:16:35.000Z

Cool we may as well write one then :) I was hoping for something that already existed.

Answer 9 · 2023-01-15T23:22:17.000Z

Here is the link to an Mdbook action from one of my projects https://github.com/opeolluwa/molybdenum/blob/master/.github/workflows/deploy.yml

Answer 10 · 2023-01-16T22:47:34.000Z

Error: -16 22:45:18 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md in "/home/runner/work/linux-for-pirates/linux-for-pirates/src" directory
Error: -16 22:45:18 [ERROR] (mdbook::utils): 	Caused By: No such file or directory (os error 2)
Error: Process completed with exit code 101.

I'm sure I'll figure this out soon

Answer 11 · 2023-01-16T22:54:23.000Z

I'm not really liking mdBook so far. I've spent about half an hour trying to get this going and it keeps failing.

Answer 12 · 2023-01-16T23:00:18.000Z

I might find something else when the time is more appropriate unless they can give us something that works right away. I could have been spending this time actually writing the book. Great idea but I'm not sure mdBook is mature enough for me to adopt it here.

Answer 13 · 2023-01-16T23:01:35.000Z

Can use the same issue but for now, mdBook is a no-go.

Answer 14 · 2023-01-16T23:07:11.000Z

Hmmm 🤔

Error: -16 22:45:18 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md in "/home/runner/work/linux-for-pirates/Linux-for-pirates/src" directory
Error: -16 22:45:18 [ERROR] (mdbook::utils): 	Caused By: No such file or directory (os error 2)
Error: Process completed with exit code 101.

I'm sure I'll figure this out soon

It's probably something with the Setup

Answer 15 · 2023-01-16T23:08:10.000Z

I won't get the capacity to look at this again for another two-three weeks. mdBook really need to improve their documentation if people are going to adopt it in their projects.

Answer 16 · 2023-01-16T23:09:51.000Z

I've been using Mdbook for almost a year and I haven't had any issue with it. That is the same reason I recommended it at first.

Answer 17 · 2023-01-16T23:10:40.000Z

Please see this for a project I was using it for.

Answer 18 · 2023-01-16T23:12:03.000Z

Your project has a slightly different folder structure and includes docs/book.toml for what I assume is configuration. I didn't see a single mention of anything like that in what I read. This isn't on you :) Don't worry.

Answer 19 · 2023-01-16T23:12:37.000Z

I won't get the capacity to look at this again for another two-three weeks. mdBook really need to improve their documentation if people are going to adopt it in their projects.

I'm quite engaged too, if you wouldn't mind, let's see in 3 weeks to troubleshoot the error. In the meantime, you can recommend alternatives

Answer 20 · 2023-01-16T23:13:31.000Z

I spotted that too, and commented out the cd docs line. If you'd like to sure thing and I'll get to it when I can. I was hoping to have this sorted for you too.

Answer 21 · 2023-01-16T23:14:21.000Z

If it were me, I'd be reaching for an alternative because once I've lost time on a project, I tend never to revisit it ever again.

Answer 22 · 2023-01-16T23:16:30.000Z

bookdown looks alright.

I'm not familiar with R language

Answer 23 · 2023-01-16T23:18:13.000Z

bookdown looks alright.

Yeah! Just checked it out

Answer 24 · 2023-01-16T23:19:18.000Z

@loftwah We sure can switch to it.

Answer 25 · 2023-01-16T23:22:09.000Z

I'd love to get to the source of the glitch once I'm free. At least for the fun of it. 😄

I'm the meantime, let's just switch to another static site builder

Answer 26 · 2023-01-16T23:33:41.000Z

I've reverted back to the default with Jekyll. I managed to get mdBook built by adding sudo to the apt-get commands but that isn't something recommended by GitHub Actions and it ended up failing again on the same thing anyway. What does this even give us anyway? What is the difference between something like that and print-friendly? I've always just used Markdown and been done with it.

EDIT: It is going to bug me all day until I fix it now hehe

Answer 27 · 2023-01-17T00:01:41.000Z

I managed to improve it a little bit with just-the-docs

Answer 28 · 2023-01-17T01:02:52.000Z

Woohoo, I think we're good :) Let me know if this is enough. I've got it generating a PDF with pandoc and I've added a link to the site generated with GitHub Pages.