Building Accessible, On-Brand Documents with Quarto

All right. Hi all. We're going to get started. This workshop, Building Accessible, On-Brand Documents with Quarto, is led by Charlotte Wickham of Posit, where she works on the developer relations team with a focus on Quarto. The session covers two areas of direct relevance to clinical research. The first is brand.yml, a configuration file that captures organization's colors, fonts, and logos once, so that every Quarto document renders consistently against the same standard, which matters for sponsor-facing and regulatory deliverables. The second is recent accessibility improvements in Quarto's PDF and HTML outputs, including the Section 508 and WCAG compliance many patient-facing documents require. Charlotte, please take it from here.

Thank you so much, Michael, for the introduction. So, hello. My name is Charlotte Wickham, and I'm a developer advocate on the Quarto team at Posit. And a developer advocate sort of sits between the people making the tools, so the people making Quarto, and the people using it. And my role is in both directions, helping people learn how to use Quarto to their full advantage, but also listening to people using Quarto and figuring out what they're struggling with and how we could make it better. There's a QR code there for the slides, and thank you for dropping that in the chat. It's there too.

Okay, so I'm going to talk about two things, this idea of accessible documents and this idea of sort of on-brand or branded documents. And in practice, these can sort of look like things like working in an area where you're subject to legal requirements that Michael mentioned, Section 508. There's the ADA Title II. If you're in Europe, you've got this Web Accessibility Directive and the European Accessibility Act. And those often boil down to, like, you must meet a certain technical standard, so like WCAG 2 or AA or 2.1 AA, or the PDF UA1 standard. And in terms of brand, that often looks like you're being asked to use certain fonts, certain logos, certain colors. Maybe even it governs the sort of tone of the language in your documents.

And these can feel like, I know these can feel like sort of these checklists or these barriers between you and getting your work out there. But I did just want to sort of take a moment to pause and, like, remind ourselves, like, why these things exist and why they're important. And I think in terms of accessibility, the thing I try and keep in mind is, like, this is all about reaching people and making sure that people can find your work. And when they do find your work, that they can access it without any barriers, that they can use it. They don't need to get help to get to the content. And in terms of brand, I like to think about this as sort of us building up trust. That, you know, assuming we're acting in good faith, people learn to know that your organization produces good work. And when they see a document that is obviously from your organization, like, they already come to it with this trust that lets them engage with it really quickly.

I like to think about this as sort of us building up trust. That, you know, assuming we're acting in good faith, people learn to know that your organization produces good work. And when they see a document that is obviously from your organization, like, they already come to it with this trust that lets them engage with it really quickly.

Demo overview

Okay. So, those are the sort of the two things I'm going to talk about. And very specifically sort of the way Quarto can help with these things. So, I'm going to jump into a demo. We're going to start with this pretty simple Quarto document. It's called 01-demo.qmd. If you want to follow along, you can find that in the demo repo. And we're going to do three things. We're going to add branding to our documents. We're going to check accessibility. And then we're going to make some customizations to the appearance of that document. And you'll see when I open this up in a second, there's one thing kind of glaringly missing from this document. And that's code and code outputs. But I will come back to that.

Okay. So, I'm going to switch over to Positron. That's where I'm going to work with this document. I've got it open here. 01-demo.qmd. If you're new to Quarto, Quarto documents end in this .qmd extension. That's how you know it's a Quarto document. And basically, there's different parts to this document. But the part at the top between these three dashes up here and three dashes down on line 17, these are all document options. And then the rest of the document is written in a special flavor of Markdown. And could potentially have code chunks in it where the code is run and the outputs are thrown in the document. And the cool thing about Quarto is that you can take one document and spit it out to many formats. So, I'm going to go ahead and render this document.

And you can hit the preview button in Positron. I'm going to use my keyboard shortcut. I'll probably use that a lot. I'll show you another way in a second. But I just want to show you what this looks like. So, I'm rendering that document. And the first thing I'm going to get up on my viewer here is this. This is an HTML version of that document. And I'm getting an HTML document because I've declared HTML as one of my formats. So, I just want to point out a few things. We've kind of got this header at the top. There's a callout here. There's an image being pulled in. And there's a very simple table. You know, we have some sort of sections and subsections in there. Nothing too crazy. But sort of the bread and butter of what documents are.

And then the other thing to notice is I've also got another format declared under format. And that's this format types. So, I'm going to render to that format. I find the easiest way in Positron is to ask to preview a specific format. And then opt into the types format. So, Quarto is rendering that now. Types is sort of this newer tool for making PDFs. So, what comes out of this is a PDF document. It's opening up here in the viewer in a PDF preview. So, we've now got a PDF. And it's exactly the same document, exactly the same content. You know, slightly different layout because now we're in a PDF. Okay. So, that's where we're going to start.

Adding brand.yml

And the first thing we're going to do is we're going to add a bit of branding. Like, can we make this look like my fictional Arcadonia Department of Health actually produced this document? And the way we're going to do that is we're going to use this idea of brand.yml. That's sort of a separate project outside of Quarto that just says, like, this is a way to specify brand in a file. Now, the thing that Quarto added recently is a specific command. So, I'm down on my terminal and I'm going to run this command that's called Quarto use brand. I kind of don't like the way that's on two lines. Just give myself a bit more room. So, Quarto use brand. And there's lots of ways you can specify where to grab this brand from. One of the ways is just as a GitHub repo. So, I'm going to use my personal user. And I have a repo there called Arcadonia brand. So, it's just sort of that user repo GitHub standard format.

And Quarto is going to go off and look for that. It's found it. It's asking if I trust the authors. I am the author in this case. But, you know, there's just brand in there. It's just being a little cautious, right? You want to be cautious you're not pulling in some random repo with a whole lot of code in it. But I am going to bring it in, unzip it, and Quarto has done a little bit of work, which I'm going to come back to in a second. But, right, the sort of first thing I want to show you is just like what happens if we preview now. I'm going to preview the HTML version. Give ourselves a bit more room on that viewer. And we've immediately got like a different feel. There's sort of this creamy background color. There's a forest green used for headings. The fonts are different, right? This is kind of that very basic application of brand. We've got our colors in our fonts. And if I show you that types version, just preview that, that all carries over here too. So, now we have a PDF with those exact same features, that cream background, the green fonts. And in the types case, you also get a logo thrown up in the top left.

So, what actually happened when we ran Quarto use brand? Back in the terminal, you can kind of see what it's doing. It's sort of like, see, I created all these files. If we look in our files pane, what it created was this brand folder. And the contents of this underscore brand folder was just a straight copy from that repo I referenced. And I'm going to go, actually, we're going to go over to that repo now. So, this is that repo, CWCM, Arcadonia brand. And beyond the readme and the gitignore, everything in here was just copied over to my project.

But the key file in this brand is this underscore brand.yaml. And this, the structure of this file is what that brand.yaml project describes. And then Quarto has implemented a way to sort of read that and then apply it to your formats. But these brand files can contain sort of some metadata, just like, who is this brand for and where could you find more info? You can specify things like logos. So, this particular brand has two different logos, a seal and a word mark. And you provide paths. Those paths are actually to files in this repo. So, there's some image files in this repo. And you can provide alt text with them. You can set up colors. There's a palette key where you can name colors associated with hex codes. And then you can use those colors for various features. And then fonts. So, typography. I'm sort of setting up some fonts I want to use and then where to use them. One for the base font, one for headings, and some other settings in there. And this brand file is sort of supported beyond just Quarto. Shiny apps can use it, et cetera. So, that's how that worked.

Accessibility checks in HTML

So, the next thing I want to show you is some ways to get accessibility checks from right in Quarto. And we'll do that. We'll start with HTML and then you'll see how we could do it with a PDF. So, in HTML formats in Quarto, there's this option called axe. And you can simply turn it on with axe is true. And this is going to run a set of accessibility checks from this axe core project. And if you have axe true, this actually shows up in the console of the developer tools of your browser. It's a little bit complicated to find. So, I actually really love this option we've got, which is, sorry, not document, output document. So, instead of showing the output in the console where I have to dig for it, show it right to me in the document. And I'm going to now preview back to the HTML version.

So, now the document's rendered. But in addition, these axe core checks have been run. And you will get this box down here. This is what's new, right? This is where the results of those checks are going to show up. And you can see in this case, we actually have a violation. So, it says there's a serious violation. And it's talking about the contrast between foreground and background. The nice thing is all the instances of that violation, we can kind of hover over and it will highlight them in the document. So, you can see this link out here. That's not meeting minimum contrast. And our cross-reference, I'm sorry. Some of my Zoom stuff's in the way. So, I can't see if you're seeing that. Hopefully you're seeing that cross-reference. Yeah, they're being highlighted over on the right. Right. So, that's a bit of a problem that we need to fix.

Accessibility checks in PDF

I want to show you sort of the equivalent in the types, the PDF output. So, in PDF outputs, this is true for types and the traditional PDF. You can now add this PDF standard key. And then list a PDF standard. So, a popular one for accessibility requirements is UA1. So, I'm going to add that. And now we're going to preview the types format. And in types, the way this works is you actually kind of get two levels of checks. So, setting the PDF standard here alerts types that that's the standard we're targeting. And types will run its own checks internally. It actually won't give you a PDF unless you meet that standard. And then afterwards, Quarto will also run a check. So, you can see, this is sort of types running its check. And then afterwards, once we've got a PDF, Quarto will run this tool called Vera PDF. And it is also taking now that PDF document, checking it against that UA1 standard, and telling you whether you passed or failed. And in this case, we passed.

And that's kind of interesting, right? Because we had some violations in our HTML format about contrast. And because we're using brand, like, we are applying the exact same colors to our PDF and we got no violation. And that's because that UA1 standard for PDF doesn't actually have any requirements on contrast. It's a lot of checks for sort of machine readability. Of this document. Doesn't check contrast. But the good news is, because we're targeting both these formats, we've seen in the HTML we've got a problem. We know we should sort of fix it and fix it in both formats.

Fixing brand contrast issues

So, in HTML formats in Quarto, there's this option called axe. And you can simply turn it on with axe is true. And in the HTML format, you can do these axe core checks. See the results right in the, on top of the document. In the browser, you've got to remember you want to turn that off before you actually send that HTML anywhere. And then in types, you can add, you can specify a PDF standard and then you'll get this check. For types, you get this check internally, but then Quarto will also run this tool, Vera PDF, to verify your Mediamat standard.

Okay, so I want to go back to our HTML version and talk about what we can do now we've got this problem. If we go back to brand.yml, down in the typography setting, we are setting a link color. So the color of the links is forest-light. We earlier set the background to be this cream. It is sort of literally a problem here that these two colors do not have enough contrast. I think ideally, if this was my organization, it needs to change upstream. It needs to change in that Arcadonia brand repo. That would solve the problem. If that was forest, problem solved.

So that's one way to fix it, right? Solve it upstream in brand. I could change it here, but the next time I pull in brand from that external repo, maybe to catch any changes or updates that have happened, it's going to just overwrite anything I've done here. So it's not like a sustainable solution. Fixing upstream would be.

But sometimes you need to do something different to the upstream brand or you can't fix it upstream. One option is to sort of look for a document option that might fix it. So there is a document option called link color and I could literally figure out what color forest was, this one, this hex code, and I could sort of set my link color explicitly. I mean, that solves a lot of the problem here. I've now got that dark color on the links. If you pay real close attention, though, and you get that table of contents back, you'll notice that table of contents element actually didn't change. And so I do sort of still have a problem on this page when that table of contents is there. So that link color, the ML option just doesn't have quite enough scope here to solve all our problems. The other problem with this approach is I have now hard coded this hex into the front of my document. And if upstream they decide that forest green is actually a slightly different hex, I'm going to miss that and sort of get out of sync with the brand.

Tweaking appearance with SCSS and Typst

So what are the other options? The other options depend on your document format. And so there's a sort of a solution for HTML, there's a solution for types. And I have these examples in the repo. So under examples, I have some brand tweak examples or a brand tweak example. It's this report.qmd. I'm going to bring that up, move that over a little bit. So this is essentially the same report, has a slightly different name, so I don't get super confused.

And this has some of those format specific tweaks. So if we're talking about HTML, the way you customize sort of the appearance of things in HTML is basically by applying your own CSS or SCSS. And that's what's happening here. So under format, HTML, we now have a theme. And that's referring to a file, custom.scss, and then just this brand keyword. So it's just, this is just a way to control the order of these things. So I wanted to find some things in custom SCSS, but I also want brand on top. And if we look in custom.scss, this is a very, let me roll it back a bit. So SCSS is a sort of like, I think about it as CSS with superpowers, like you can define variables and you can have functions and things like that. And Quarto has a very specific way that you have to specify these SCSS files, and it involves these special comments. So these special comments, there's about five different variations. They're basically structuring this file so Quarto knows where to kind of plug them in to its pipeline.

But the two you use most often are this default section and this rule section. And in the default section, you're basically defining variables. And Quarto has a set of these SCSS variables that control various aspects of the appearance. But one of them is called link-color, and that controls the color of all the links. And the really nice thing about what's happening here with brand is that Quarto's also creating these variables based on your definition of brand. So once I'm in the sort of SCSS realm, I can actually refer to colors from my brand in this SCSS variable way. So all I'm saying in this default section is that link-color variable should take the value of my forest color from brand.

In the rules section, you can basically just put other CSS, you know, regular kind of looking CSS rules. The one I'm adding here is for h2 headings, don't put a border on them. So this over here on the right is our original rendered report. And you can see there's this kind of pale gray line under this introduction heading, and it shows up again under, oh I guess I don't have any lh2 headings. It doesn't show up anywhere else. But I don't really like this. That treatment doesn't happen in our types document, so I kind of just wanted to get rid of that. So if I go back to the report that's using these custom files and make sure I preview html, we should be able to see that even the, okay you're not going to believe me unless I have that table of contents there, so let me just give myself a little bit more room. Okay, right, we've got no XCore violations found. We've fixed that link contrast problem, and we also got rid of that gray line that I didn't really like.

So that's the sort of solution to tweaking the appearance of html documents, if there's not like a yaml option that's going to solve it for you. In terms of types, the approach is a little bit different, but I'm doing it in the same, I've got an example of it in the same format, sorry, the same document. So down here, right at the start of the content, I'm just including another file. This is a standard Quarto thing, so this is a Quarto include. It's a shortcode that just lets you pull in from another file. Just using it here to kind of keep my style and content separate, sort of and mirroring that idea of keeping my customizations to the SCSS in a different file. But I'm just pulling in another file, and if we go look at that file, it is in fact, I saved it as a markdown. I've actually changed the file, I should have done this slightly different, but anyway, just think about this as like this, I could have dropped this right into that Quarto document. I'm just putting it in a different file for ease.

What's inside is first, notice this triple backtick, curly braces, that they would normally have you thinking like code cell. It's not a code cell, quite. The equals types means it's a raw block. And what it means is that whatever's inside here is just straight up types syntax. And it will, Quarto will ignore it, it'll just let it pass all the way through to types. And the other advantage being that then it won't come, won't get accidentally sucked into our HTML version.

And then what's happening inside this types block, so the way types kind of defines sort of rules for styling is these things called show rules and set rules. Set rules are a little bit simpler, they're just like saying, hey, whenever you call this particular function, set some of the arguments to these values. Show rules sort of let you do that in the scope of something. So the way that I kind of think about this first one, for instance, is we're setting a show rule anytime there's a link. And what's happening is that the text function will have the fill set to this forest color whenever we're calling that, whenever a link is being used. So sort of like the SCSS, you have access to your brand colors inside types.

Interestingly, in types, links and cross references are sort of different kinds of elements. So if we also want our cross reference to get this color, we have to add another show rule for that. I've also got this show rule here that's essentially taking anything that's a cross reference and adding an underline. You can see in our HTML version, our external links and also our cross references had that underline. Kind of wanted to keep that consistent between those two formats. And then this last show rule, I'm really, I don't, I sort of feel like the types headings are really cramped. They just don't have enough room to breathe. So this last one is just giving every heading a little bit more space above and below it. And if we go ahead and preview now our types format, you can, you'll be able to see once it finishes, that those changes have taken effect. So we've got those dark green links, even cross references have that color and they're underlined. And these headings just have a little bit more room than that default one we had before.

Using template partials for layout control

So that's sort of like when you just need little, little tweaks. You've got this SCSS option for HTML. You've got this types set and show rules for types. When you want to control more than just like little, little things, for instance, you might actually want to control the layout. So I think a lot of people sort of see this types PDF output and they're like, yeah, that's cool. It's a PDF, but like, it's not how PDFs have to look in my company. Then the next sort of step up in tweaking appearance, you want to use these things called partials.

In that process of your Quarto document becoming a PDF, for example, Quarto is doing all the work to turn the content of your document into these types commands. But then the content of the document sort of just dropped inside a template. And it's the template that's defining things like how the page is set up and some of this default styling. And you can either replace the entire template or these partials are like little pieces of the template you can swap out and do your own.

So here's that same report. Basically, again, the big difference here is that under the types format, I've added template-partials. And these partials exist for all the formats, but the way they're organized is different for each format. So in types, there are a set of partials and they have very specific names. You have to keep the name the same. So I'm replacing three of those partials in this example. But a lot of the content of those partials is just whatever the default is, plus a few tweaks. So what I really want, I can talk about them more, but what I really just want to show you is like what this lets you do or what this gets you.

So I'm going to re-preview. So now we're using the same report, different set of partials, still heading to PDF through types. But we've really got sort of a tweet layout. So the big differences here are I've changed the way that that title block operates. So I wanted my logo off to the left, but with an underline under it and the title above that underline, author underneath. And this is a little bit different too. I can't show you because I've only got one page. If you use the default template, you usually get your logo on every single page. In this template, I've made it, you see the logo on the first page, then not at all after that. The other thing that these template partials are adding is a footer. So it's just got the title and the date, page numbers still there. And then also some sort of changes to the default handling of tables. So this template also says, hey, whenever there's a table, make sure it's centered, do those kind of, the line style where you have like, you know, heavy top and bottom, a slightly lighter line after the header and otherwise no lines.

But those are the sort of things that you might need to reach to a partial to achieve. So when sort of the requirements you have go beyond just, I want this background color, this foreground color in this font.

Applying brand to code outputs

So the big sort of glaring omission in that document is that it doesn't have any code output. So let's go back. I have this other demo file at the top level, O2 with code. So this is really right. This is why people use Quarto. This is where Quarto excels is that you don't just want pros in this document, right? You want code that's creating plots or creating tables. Let me get that rendering to HTML. So in this case, there's a sort of a setup cell here. This is just reading in some data. There's another cell a little bit later that's creating a plot. It's doing it with ggplot2. And then a little bit later still, there's another section creating a table with the GT package. And that's all well and good. We're still using brand, but your code outputs will not pick up brand automatically. So we kind of get these like starkly out of place plot and table with their white background and grays and like it just doesn't look great, right?

So, you know, these are packages that are creating these plots, aren't going to pick up brand automatically, but there are ways to kind of provide this linkage between your brand and those packages. So let me talk about that a little bit. So I'm going to go back up in my document just after that setup cell. I'm going to add a new code cell and just show you. So there's this package, an R package called brand.yaml. And the big sort of thing in that, the big function in that package is this one called read underscore brand underscore yaml. And if I run that, like this literally picks up brand the exact same way Quarto was picking up brand, right? It looks for it in certain places. It finds it in inside this project and underscore brand underscore brand.yaml. And it reads that file and passes it nicely. And if we save that into something, so I'll call it brand, we can then explore it. It's a special object type, but basically it works like a list. So I can go into my brand. I can go into the color section. I can look in the palette and then I can find that forest color and there is that hex code.

So that sort of gives you that nice link, right? Now our code cells can know all about our brand settings. And then using it is going to depend on the packages you're using. So for ggplot, the really nice thing is that the theme function. So this is my plot. It was using theme minimal and all the theme functions. As of 4.4.0, I think, take some arguments that make it really easy to do branding. So there's an argument that's called Ink. And I could literally say, OK, I want my brand color. I want the foreground. and I could literally say okay I want my brand color, I want the foreground, let me just check, I'm a little worried that I wasn't getting, oh yeah that's it, and then there's another argument called paper and that I can give as the my brand definition of background, right, and that alone, I'm just going to re-knit as opposed to running that in the console, right, that alone takes away that glaring white background and makes it look a lot more in place.

I'm going to go back to the slide, so this is sort of, you know, it doesn't get picked up automatically, but it's not too bad to kind of bring it in with this brand.yaml and then wire it up, so we saw sort of the ggplot example, like you can use these same functions, that's one way to do it, gt, if you've got gt tables, the brand.yaml package has some helpers, it has a ggplot helper, it's called theme underscore brand underscore gt, so you can just apply that, doesn't handle the font, so you have to do that separately. I see a question, is there an equally simple way to use branding with Plotly? I'll tell you, that's an excellent question, so the first thing I would do is check brand.yaml and see if it has one of these theme, yes, it's got one of these helpers, so there's a theme brand Plotly function in brand.yaml, which claims to apply brand colors to a Plotly plot.

I don't know if I've got Plotly installed, so we can just, we could try, no, I don't have an install, but I think that's probably what you're looking for, that should do it.

Accessibility in documents with code outputs

Okay, and that gets you to this point where you can have these documents that really do reflect the brand, both kind of in the narrative content, but also all of your code outputs, and there's those two, html and pdf versions, and I have that over in demo end, I'm just going to get this one up, 02 code, complete this one, okay, so I'm just gonna, let me just render this one, because I want to show you something. So I've wired up that brand here, I think I even wired up, yes, I'm like using some of the brand colors in the ggplot lines, you know, you can sort of do that as well, and what I wanted to point out is that as soon as you start having outputs from code, your accessibility violation will probably explode. That's kind of just the nature of where we're at right now. So this particular one, it's minor, it's coming from this axe set, but it's complaining about this table, it's saying the table header text should not be empty, and in particular it's complaining about this cell here, right above age.

So this is sort of like where we are, like this is what your life is like when you start enabling these checks, like you get violations, and then you've got to figure it out. So what can you do in terms of authoring accessible documents? Using Quarto actually naturally encourages some really great habits, like using semantic structure. So it's basically impossible in Quarto to just style something like a heading without making a heading, it's like just so much easier just to make it a heading. And it naturally encourages this sort of reading, or like the way that you write your content from top to bottom in your QMD is going to imply that's the reading order that you want.

And these automated checks will catch things, right? The one that I'm always getting caught on is when I forget to add alt text, it'll catch that, so you want to set that fig-alt attribute or code option, and you'll get picked up on various contrast things. But automatic checks aren't enough. So the things like, they're just things you cannot automate, right? Like you cannot automatically check if your alt text is meaningful, or if the pdf tagging structure actually reflected the logical structure. If your charts are readable under color vision deficiencies, or if your tables are coherent under cell-by-cell navigation. And I think ultimately, like, can a real person who relies on assistive tech actually use your document? Like that, you just cannot automate those checks.

can a real person who relies on assistive tech actually use your document? Like that, you just cannot automate those checks.

And it means, so you will get these flags from automatic checks, you will also get things that fly through, but then somebody says, hey, like this isn't actually accessible. And that's where it gets kind of really, really complicated. So you could imagine that somebody reading your work reports an issue, and let's imagine they're reporting an issue with a table in your pdf when they're using voiceover in Adobe Acrobat Reader. And voiceover is a Mac thing, so this person's probably on a Mac. So the question is, like, where's the problem? Where's the fix go? And it could be that it's in your code, right? It could be that you just used your table package in a way that resulted in something that wasn't accessible. But there's an easy way for you to fix it in your code. Or it could be that you maybe changed the way you're thinking about a table. It could, like, if you're using GT or some other package, it could literally be in that package, right? It is taking your code and pumping out some kind of output. And GT and the examples I've been giving is pumping out an HTML table. It could be that GT is pumping out an HTML table that has something wrong with it in terms of being accessible. It could be that Knitter is the issue, right? Like, the way your GT table gets into your Quarto document is it has to go through Knitter. Knitter is in charge of running that code, collecting the output and chucking it in this intermediate markdown format. Maybe something's going wrong there. Maybe Quarto is doing something wrong, right? It gets in there, too, putting stuff around these objects or possibly even going in and editing these objects. Pandoc's in charge of taking a markdown and turning it into a .typ, like a types document. Maybe it's doing something weird. Types is in charge of turning a types into a PDF. Maybe there's something wrong with its process. Maybe Adobe is interpreting the PDF weirdly. Maybe VoiceOver is doing something weird with Adobe's interpretation, right? It's just really complicated.

So, sort of in reality, in practice, right now, there are you, like, sort of should expect that you might have to do some sort of workarounds, right? Like, if the fix really needs to live in GT, we would love if you opened that issue, but you might have to come up with a workaround until that issue is dealt with and solved. Same thing with Quarto. Like, even if you're not really sure if the problem's in Quarto, like, if you let us know that you're using Quarto, you have this problem, who else is involved? We're sort of interested in hearing that. So, the landscape right now, especially with PDF, because these accessible PDFs via Types or LaTeX are so new, there are a number of issues, but I think as people use these checks, use these tools, open issues, things will get better.

Q&A

So, that's sort of what I had planned. And we've got plenty of time for questions. It looks like, yeah. If you want to, you can unmute and you can ask your question yourself. It looks like Andy has his hand up. Yeah, hi, Charlotte. That's okay. This is a great presentation. I really appreciate it. As you know, we've been working on this for a bit. And I had a question about I think I might have missed it. So, for your logo that you were pulling in that was in that top left-hand corner, what format was that in? I'm pretty sure I have any. What do I do? I don't know. We'll go have a look. The SVG. Yeah. Yeah.

Okay. And then, do you, have you gotten any feedback about when people are using screen readers to read through? What does it, I don't think you can add alternate text to the logos. Have you found a workaround for that? We've noticed that. Hmm. Yeah. So, it should flow through. But, I mean, I'm not going to be surprised if it's not or there's something going wrong. And it could be. So, there's a lot of things going through. So, brand has its way to provide alternate text. Oh, okay. Perfect. So, that should flow through. But there's two, I would double check. So, we can, and we can actually probably look. So, this is an excellent reminder. Let's go back to our very first one.

Sure. With it complete. So, the most useful debugging tools are these keep functions. So, keep type to keep the type. You can keep MD to keep. That will be after any code. Not so important in this example. And then, I'm going to redo, sorry, redo the types version. We should be able to dig a little bit. So, I'll let that finish. Oops. Something went wrong. Okay. So, that's just a problem with my, I will fix that later for you guys. That's a problem with my repo. Okay. Let's go back here and do this one. So, keep type true. Type true. And then, we should, oh, of course, I've got to go to types. And then, we should have a, once that's finished, we'll have an 01-demo.type. And this is where I would start looking for that logo. I think I called it wordmark. All right. That's where it's being pulled. In this case, well, so, there it's, this is the definition of them. So, let's see if we can find where it's actually used. But it does. That flowed through okay.

Oh, great. Okay. So, you, okay. So, you did that when you set your, when you're using the logo, I don't know the right language, but you were like setting your logo preferences. Right. So, this is in, yep, underscore brand. When I'm setting up those images, when I'm calling wordmark, I have both the path to the image and the alt text. That's incredible. At least we verified it flowed through to the top.type file. We haven't verified it flowed through to PDF, but I think our validation should have flagged it. Okay. Yeah. That was a problem that we've been having is the logo was kind of coming up in an error through screen reader. So, this is great. Thank you so much.

Charlotte, I have two questions. So, first, the examples you showed were for HTML documents and PDF documents. How well does this extend to slides and then also to Microsoft Word or PowerPoint? Yeah, yeah, yeah. So, slides, so, if you're using the reveal.js format for slides, this should all work as is. So, you should be able to just plop the brand in. It'll get all the styling, and you can add the X document true. And, in fact, I have this. I've activated it on this slideshow, right? It's a little bit different. Instead of a box sort of floating, you get this last slide that actually gives you that report, but that's fine. Microsoft products, like, the reality is, like, no. So, we don't support brand on them at the moment, and we don't have any form of automated checking for those.

Okay. And is that mostly because of the Microsoft rendering process? There's already some pieces there. Yeah, it's the, yeah, it's just complicated, right? We basically do not, Quarto basically doesn't touch much of the Microsoft rendering beyond what Pandoc provides, and we're sort of not going to invest in doing something different from Pandoc, and it doesn't look like Pandoc is, like, it's just not a high priority in that realm.

Okay. All right. Other questions? And then, I guess another question for me is, so, then, what is kind of the the roadmap for this? Are there plans to, like, you could think about having, like, within an organization, a set of branding, but then even, like, externally, you know, instead of packages, you could have branding for things like journal articles or things like that. Right. Yes. So, I think, like, if I was an organization that made a lot of Quarto documents, I think it would probably look like, like, there would be possibly just a single standalone brand repo that's sort of tool agnostic, right? It doesn't care if you're using Quarto or Shiny, like, just somewhere central that records those things. Then it might look like, you know, an R package that sort of has all the helpers to apply that consistently to the packages that people are using in the organization. And then possibly, like, also a Quarto extension that sort of adds on these templates for, you know, what does a PDF look like at our organization, or what does an HTML page look like for our organization? And I think that's all possible now.

And I guess we're sort of, like, hands off on that. Let us know, like, try it and let us know where Quarto's letting you down.

And then, sorry, just one more question for me. You said this does extend to Shiny, is that right? So, Shiny has, yeah, this is not my area of expertise. Like, I know there are some tools that will help you get brand applied to your Shiny app. I forget exactly where they live, if they're living in brand.yaml or maybe something like BSLib or something like that. So, don't quote me on that. The best place to look was probably on Shiny somewhere. I can follow up if anybody's curious about some links to that.

Okay. Other questions? All right. Thanks very much, Charlotte. This looks really good. Yeah. No worries. Pleasure being here. Thank you all.