For HTML report generation, should CSS be put into stylesheet or written into the html file?

Question

I'm writing a report generator for an automation tool.

Right now I have a report template html file which is read by the generator and the results are filled in by the tool to be written to another html file.

I suppose the benefit of using the <style type="text/css"> tag inside the html file would be that the report can be copied (or emailed) as a single file, while having it link to a stylesheet would require that the stylesheet to be copied along with the html file. A stylesheet file would save a small amount of space but I'm not sure if that's really enough justification to use it. I suppose while writing the css styles it would be easier to have it link to a stylesheet so I don't have to generate a new report to view my changes across multiple already generated report files.

These html report files won't be hosted on a website so caching doesn't need to be considered. It's likely the report will only be viewed once or twice and then deleted or archived. The report file can either be automatically generated to a Temp folder or manually generated to a user specified path.

Would it be better to write the CSS into a separate stylesheet or write it directly inside the generated HTML report file (actually all css styles are written in the template file)?

Answer 1

In a web-serving context, putting the stylesheet in a separate file is MUCH preferred. It will lead to much better in-browser and in-Web-middleware caching behavior, so have much better performance (and impose lower load on all of the systems involved). There are other benefits as well (e.g. better modularity, versioning, ...).

But that's not your case. You seem to have a situation where having a single, all-inclusive, self-contained HTML files would be preferable. The parts of the document (like CSS) that can be separated...well, if someone's not careful in transmitting the files, they will be separated. And then the document won't "look right." It will look broken. Perhaps very broken, depending on how much you rely on CSS. So by all means, embed your styles.

Aside About Images and Email

In HTML, images are often left external. For truly self-contained files, you'd like them to be included too. That is now generally possible if you base64 encode them. There is a older alternative strategy, MHTML, for sending images and other content through email. Directly stating base64 data seems to be better supported these days, especially for browser viewing.

But if you are encoding HTML (reports, documents, etc.) for email (i.e. as the primary email message, rather than as attachments), beware. This is a bit of a dark art, even today requiring a lot of expertise about the vagaries of the different end-points/mail programs. Outlook vs. Gmail vs. XYZ--they can be very different, not only from each other, but also from the HTML you would use and expect to work correctly across their browser products. Email HTML is a tricky devil, and it doesn't play by the normal rules. Stylesheets there, for example, are not recommended at all, because they will often be intentionally disregarded. If you want to style those, write your stylesheet for composing your HTML email, then use a library to deconstruct your stylesheet and explicitly pack the appropriate styling into style attributes. See premailer for an example of a library that helps you style email HTML in a way that will be respected by the average mail program.