search

aya-rs / book

The Aya Book is an introductory book about using the Rust Programming Language and Aya library to build extended Berkley Packet Filter (eBPF) programs.
https://aya-rs.dev/book/
Apache License 2.0
79 stars 60 forks source link

Fixes codeblock indentation in order to make them actually work #184

Open arielf212 opened 7 hours ago

arielf212 commented 7 hours ago

Currently the documentation website shows broken code blocks, this PR provides a fix to that :)

netlify[bot] commented 7 hours ago

Deploy Preview for aya-rs ready!

Name Link
Latest commit bc865c8fa0d51fe8a895b666faff28007101971d
Latest deploy log https://app.netlify.com/sites/aya-rs/deploys/6746081dfb40bd00087e44fe
Deploy Preview https://deploy-preview-184--aya-rs.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

arielf212 commented 6 hours ago

Done! Thank you for your guidance! :)

arielf212 commented 6 hours ago

Yeah, just hopped in to see what the CI is yapping about now. Seems like I can't fix most of those problems, since that would break the intended look of the page. In general, I am not sure this utility is very useful for mkdocs, since mkdocs uses a lot of non-standard markdown extensions :)

arielf212 commented 6 hours ago

I found myself copy-pasting a lot of enable/disable pragmas into the codebase, which I found really ugly. As such, I just disabled two very noisy rules and fixed the remaining one. As I described in the commit message, the codeblock rule fundamentally clashes with how mkdocs works, while the second rule (dollar sign) clashes with the already-set convention for this repo.

vadorovsky commented 5 hours ago

In general, I am not sure this utility is very useful for mkdocs, since mkdocs uses a lot of non-standard markdown extensions :)

To be honest, the only reason I decided to introduce it is that we used to have a lot of places with over 200 charaters per line, weird whitespaces and inconsistent heading. And also a lot of PR introducing more of them. :sweat_smile: I'm not a big fan of nitpicking such stuff as a person (it gives people room to come up with completely arbitrary rules), so I would rather have a linter making sure that *.md files aren't unreadable. I agree that some markdownlint rules are questionable and not compatible with mkdocs. Unfortunately, I don't think there is a good alternative. So I think we just need to figure out a minimal set of rules which make sense for us to use.