search

sst / guide

Repo for guide.sst.dev
https://guide.sst.dev
MIT License
3.68k stars 444 forks source link

PDF version rather broken #257

Open LosD opened 6 years ago

LosD commented 6 years ago

I normally like to use the PDF version of guides, but the PDF version of your (otherwise great) guide is pretty terrible compared to the web version:

I realize most of this is because it's not easy to make PDF-friendly pages in Markdown, but especially the dead links are annoying, and I'd expect the tooling to try to avoid page breaks at silly places when possible. Are there really no good MD to PDF tools, or is it a matter of configuration?

I'd maybe also consider finding a way to scale back on the "help and discussion" links. They're huge and annoying in the PDF. Maybe just have an icon that links to the relevant h&d page (with a note on what these icons are in the preface)?

Anyway, thanks for an amazing guide. It really takes a lot of the doubts and questions out of starting with the AWS serverless products!

LosD commented 6 years ago

Ah, I see you're already looking for better ways. I'll leave this open for now, maybe then it can function as a kind of registry over some of the drawbacks to the current way (I guess it's MD->HTML->PDF).

jayair commented 6 years ago

Yeah I haven't been able to find a good way to generate a PDF from the Markdown files. Currently all we are doing is creating printable versions of the chapters in HTML and using Safari to generate a PDF. Ideally, we'd like to find a better way to do this and to automate the generation of the PDF when there is a commit.

pepas24 commented 5 years ago

Hey @LosD, we are working in this improvement, please take a look a this pdf version and epub too and give us your feedback, still needs improvements, but as its so long its better to have more eyes on it.

LosD commented 5 years ago

@pepas24 It's been a while, but from what I remember, readability has improved A LOT :)

Still some issues with code and tables crossing page breaks when small adjustments could have avoided it, but I'm not sure there's really a way around it without either some stringent rules, or manual inspection (and of course, sometimes it's just too long), so it's probably not worth it to fuss too much about.

Still quite a few problems with fitting text and images. For a pretty bad example, check page 660-672: There's a sentence and an image on each page... But the text is always referencing the image on the next page, making the whole section rather confusing. I realize that it's not easy to fix, but in this case, I think the extra work would be worth it to help readibility.

Unfortunately, there's still no links to sections in the TOC.

Anything I can do to help?