How to make HTML reports acceptable to medical audience

At the end of Frank’s talk in RStudio 2020, a question came up that I am confronted with every time I create a medical report: “How do I make HTML report acceptable to a medical audience”

I believe the main problem was not addressed: The need for annotation directly in the report. When I meet good-willed researchers, they read in HTML in Word and use Word or PDF annotation tools to add additional queries. Big bosses normally are not good-willed and ask me for a Word-version, accepting that any interactivity as possible with the DT package or ploty is lost.

We should take this problem serious; it is not a question of age.

There is one online tool I know to edit HTML (The Hypothesis community — h 0.0.2 documentation) which comes close. However, it is always argued that online-tools are not acceptable for clinical reports because of security issues. This might be a bit of a European problem, when I talk with US friends they always argue “why not use a server based method”? No way after Edward Snowden.

To make HTML acceptable, we need some desktop tool that can be used to add annotation to HTML reports without a server, and that writes annotations back into HTML in a self-contained format.

Any ideas?


im really out of my depth here, but quite interested in this. I’ve been playing around with fidus writer and some other apps over the last days. With regard to your Q, perhaps dokieli is relevant?:
“dokieli articles and annotations are completely decentralised! This means that authors can publish where they choose, and we have no central servers to monitor or control your content or the interactions of your readers. Simply add the dokieli CSS and JavaScript to any HTML page to immediately add in-browser editing and annotations. You can download the dependencies to work offline, or use them directly from Use in-browser local storage to save your changes or export to save to your harddrive, and to any Web server when you’re ready to share your article.”

1 Like

Thanks, I did not know this and it looks promising. I will give it a try!

Reading the homepage is somewhat un-inspiring, here is a better link if you need a first look: looks like a good solutions, after 2 hours of reading the documents that describe “what you can do” in full detail, I have not been able to prepare a simple document that I can edit without connecting to a server.

I think that browser-based solutions will not work anyway, because to get a self-contained document after editing one has to write back to it, which is a no-way for any browser. Local storage as offered by is no solution (in case I should get it to work) because it cannot be repackages as a new html without some non-browser tool.

1 Like

I am so glad that Dieter has restarted this discussion. We have recently begun using interactive html reports produced by the R hreport package and giving them securely to clinical trial Data Monitoring Committee members for review. Access control and annotations are important. My colleague Bob McClellan wrote a secure web portal for this purpose but his approach would work for html reports in general once you take the time to define user roles, IDs, and passwords for access control. Bob did an excellent job with the annotations, which are stored on the web site and always remain connected to reports by location. The location link is done through metadata in html reports that is created whenever you have a # Section Title, ## Subsection Title, etc. So the report creator can update the report arbitrarily and the annotations will stay in the right places as long as subsection titles are not changed.

I’ll ask Bob if he’ll join this discussion. I think that if each institution or major project area were to have its own server for running the portal, you’d have what you need.

There is a very general html annotation web site, whose name I’ve forgotten, that I tested years ago. It was well designed but when the document was more than a few pages long the system ran too slowly.

I would like to find a system that allowed annotations to become formal parts of the report. Until then I’ve found it useful to use various levels of quoting (indenting) from within an R markdown report. This requires manual curation.

1 Like

Thanks, Frank, for your comments. If I understand correctly, your solution also depends on some server. This would be ok for the department’s security team if it is on the intranet and locked from the outside by a firewall - which is not very helpful when several clinics are involved.

If you accept such a solution, the hypothesis server works well out of the box and installs easily.

However, I have encountered another psychological problems: Researcher commenting on some manuscript do not want a trail of their edits, because they fear that intermediate comment could be embarrassing. When I see think of some of my github trails left behind trying to get a package through CRAN, I can understand this, github works like an icewater bath for your resilience.

I think only a standalone editor that includes comments into HTML files will make these people happy. The believe that only your laptop is a safe haven might be a little naive, but many believes are.

1 Like

A couple of random thoughts. First, and our approach does require a dedicated server, the team members can add both private and public comments. Private comments are seen only by that person; public comments are seen by all members of that particular team (in our case, a clinical trial committee). Second, I would love to have an interface that automatically adds links to permanent comments into a markdown file. Bob’s approach would allow that since you could key by subsection label, if he write an API that would pull comments off the server.

So it is:

HTML > Reviewer1 > Server > API > modified HTML > (mail) > Reviewer 2

Again, we have the server problem: All clinics I know will cry Zeter and Mordio when it comes to installing some type of server.

Word on hospital computer > Reviewer > Save Word > copy to laptop > Reviewer continues > mail > Reviewer 2

Also works with PDF. I almost never use Word, but I have to live with the status quo. Hospitals have good reasons to run a tight shop.

My preferred way:

  • AnnotDown: JS in a standalone markdown-generated HTML to annotate and keep results in local storage. AnnotDown also displays annotations from a previous edit
  • A small desktop program to write the annotations back to the original document HTML - ugly, but I do not know of any better way to write from a browser. The program should be very small and have some security audit, because otherwise the IT department will cry.

It’s not as easy as 1-2-3-Word, so I am not sure this will be accepted by the audience.

Would you provide a link describing AnnotDown:JS?

I think that keeping comments on a public server or in a local file and placing URLs to individual comments in your main document may be better than inserting whole comments. On the other hand we should take a look at CriticMarkup.

1 Like

AnnotDown: Sorry, no link, just a pun, referring to markdown, pagedown, bookdown, updown, and down-under…

on a public server
that’s what causes my people headaches

or in a local file
Could be ok, if some easy binding method were available.

1 Like

Just like Rmarkdown compiles to HTML file, there should be a way to annotate a file and resave the results with the HTML. There are several barriers to overcome. First is security, static web pages are in general denied local file system access due to the number of abuses this would allow. Assuming one could save a web page with modifications and pass on just like a Word document, the trick would be creating a robust javascript library that does the task. This wouldn’t be too bad. The third major hurdle then would be changing default behavior. Word is deeply ingrained to the point of absurdity in many workflows. I asked for someone to send me a quick email with the remaining task lists on a project. I got an email with an embedded word document. So now I have to download the file, open it in Word, copy and paste the list out, strip the formatting (which took two tries), close the document and delete the document. It could have just been typed in the email, but this is all too common practice. However, it is a very attractive idea to be able to annotate html with comments and share. I think this would catch on in the tech communities quickly if it was available as feedback on web development would be a lot easier than annotating in a paint tool which is commonly done today.


Strikes a note in me, I have seen this before.

First, thank you for including me, @f2harrell! To @spgarbet’s point, having Javascript write to local file is bad, however HTML5 introduced web storage which allows for greater amounts of data to be stored locally than cookies permitted. It might be possible to create a browser extension that utilizes this storage for annotations. This would be fine for local comments, but if one wanted to be able to pull in “public” comments for a report and not have a central server, then this extension would need a way of exporting comments that other’s could import. Of course the complexity increases with different browsers all needing their own version of this proposed plugin.


Which is quite exactly what I wrote above:

My term “AnnotDown” was a bit misleading, though, even Frank believed I could send a link…

I don’t know very much about epub, but in core it is HTML and has annotation.

Has anyone given it a thought?

If you want to see a super elegant paint-type annotation tool for html, see Zoho Annotator. The result is saved as a png or jpg file.

I found this:

Mozilla has a plug-in which does this for a webpage.

1 Like

Interesting, it is even a “Recommended” plugin. We should revise our prejudices on what browsers can(not) do.

As far I can see, SingleFile only writes the unmodified HTML File, which you could also do with other tools

I am also very interested in finding an easy to use solution to allow clinicians to edit (e.g. add conclusion) to a PDF | HTML report.
I tried many of the tools mentionned in this thread, but they still come short.

On my side, currently trying to think about a Shiny | Jupyter notebook setup.

Keep us posted !

1 Like