bazel-pandoc
bazel-pandoc copied to clipboard
ProdriveTechnologies
Generation of HTML documents with custom CSS
As requested in an issue, this PR implements the ability to generate HTML documents with custom CSS defined in a separate stylesheet.
The output can be reproduced by running: bazel build @bazel_pandoc//sample/...
Known limitations (a.k.a. improvements which could be implemented before merging with master):
- Only works when
to_formatis specified in your rule. This limitation was added because otherwise the--css-flag is also appended for non-HTML files. This results in an error for some conversions. In fact, this limitation could be resolved by using `-c' instead, but then the CSS is somehow not included. - Standalone flag
-scould be added, but thenbazel-pandocshould also output the CSS file itself.
Nice! I don’t know this feature of pandoc well. Can multiple css files also be provided? I'm not an experienced pandoc user at all, but at least the documentation doesn't say anything about the usage of multiple CSS files.
Nevertheless, I put together an additional CSS file and included it as follows:
pandoc --css stylesheet.css custom.css -o output.html README.md which doesn't give the desired result, since only custom.css is included as a stylesheet.
But generating a stand-alone HTML file using:
pandoc --css stylesheet.css custom.css -o output.html README.md -s includes both stylesheets into output.html. Unfortunately, the W3C mark-up validator won't be happy. Since stylesheet.css is wrapped in a pretty nice <link />-tag, but custom.css is just included in the <body> using <style></style>... Moreover, as mentioned in my first post the usage of the stand-alone flag requires some additional work to properly function together with bazel. Feel free to contribute ;-)
Interesting. Maybe I'll poke around for some pandoc projects and see their approach to css with regard to theming. If it has to be one file in the end, I guess you could always do something like pull in https://github.com/bazelbuild/rules_sass and build out the file using sass. And maybe the same approach with making it interactive with js?
Interesting. Maybe I'll poke around for some pandoc projects and see their approach to css with regard to theming. If it has to be one file in the end, I guess you could always do something like pull in https://github.com/bazelbuild/rules_sass and build out the file using sass. And maybe the same approach with making it interactive with js? That would be great!
At this moment in time, I'm not actively developing new features for bazel-pandoc myself. Nevertheless, your thoughts on this are interesting and are could be of some real added value to bazel-pandoc :)
May I ask what you are using bazel-pandoc for? Since interactive JS is something your could call out of the ordinary for just a tool which converts - for example - documentation from markdown to HTML. When you are thinking about using interactive JS I would rather consider developing a stand-alone website from the beginning, instead of using pandoc.
I just tried out the changes and it works great. The only thing that stands out is the need to wrap the css in a style tag. Other examples I've found don't seem to require this: https://benjam.info/panam/, but maybe they were written against an older version of pandoc?
Hi sorry I'm kind of a github noob so I'm not sure it's the best way, but I created https://github.com/ProdriveTechnologies/bazel-pandoc/pull/16 which deals with the issue of the CSS file not being copied over, and adds a "data" attribute to solve the issue with other media like images that can be referenced from the generated document and need to be copied over. Maybe I should merge into this PR but I'm not sure how, sorry.
