Headings the Right Way: Site Building Tips for Accessible Page Content

In this talk, Mike McAffrey discusses best practices for using headings in web development to improve accessibility and usability. He emphasizes the importance of using HTML heading tags (H1 through H6) to create a structured content hierarchy that aids comprehension, navigation for screen reader users, and search engine optimization. Mike highlights common accessibility pitfalls related to headings, such as multiple H1 tags, skipped heading levels, and visually distinct elements that lack proper semantics. He shares several methods for implementing headings effectively within Drupal, including using CKEditor, field groups, and paragraph modules. Throughout the presentation, Mike advocates for proper editing interfaces and automated processes that assist users in maintaining accessibility standards.

All right, folks. Uh, welcome. This is headings the right way. Site building tips for accessible page content. Let's Hello. Uh, I'm Mike McAffrey. I'm a senior architect. I work at Calamuno. We're a small web development agency that builds sites for nonprofits, education, and government clients. Um, I also facilitate the Calamoon accessibility practice where we discuss the best way to build websites and try to set internal standards.

I'm a bit of a neurodeiffer person and I've kind of an obsession for building things the right way. Um, and that includes being as accessible as possible. Um, I have a strong focus on usability, including making the editorial experience uh, good for the users, which is often something that is lacking when people set up Drupal sites. Uh, one accessibility note, I I did put lots of bulleted

lists on my on my slides and I'm going to discuss all them in order. And, uh, no, that's not the way you're supposed to give a presentation because, as everyone knows, it's better to tell and not show. But uh this might not be as compelling, but I'm going to do it hopefully for accessibility. I want uh folks with hearing issues to be able to follow along. I

want folks with attention issues to see what we have just discussed and they missed because I always do that. Uh and also I'm going to describe things to help listeners know what is on the slide and hopefully it'll keep me from forgetting things. Uh there is a picture a blue ear. It's from my my blog series web design web design for disaster which is on the Caluna

site which I suggest. I'm going to go back for a second. Uh in case you can't see the slide or me uh I am a tall white guy with a beard, glasses, and a cap, a t-shirt and a lanyard. You know the usual. All right. So you might be asking headings. Are headings really that important? Well, on the slide, we have two different examples of text. On

the left, it's just some Lauram Ipsum text, just blocks of paragraphs. And on the right, it's the same content, but with headings. And I don't know about you, but I find the one on the right would be a lot easier to read. Uh, headings in HTML. There are six heading tags. H1, H2, H3, H4, H6, and H5. Uh they divide the content of the page into sections

and summarize the purpose of each block of text. They are organized hierarchically by like heading level one, two, three uh in order to add structure to the page and to the content. They're important both for the comprehension so you understand things while you're reading them and also for wayfinding. So when you're trying to find a piece of content within the text, it'll help you identify what part

to start reading. They stand out visually for cited users, so you can sort of see them and scan down the page. And they're one of the most important targets for screen readers. Uh often times a screen reader, you might be going down the page, hitting the H key to go review all the different headings on the page to see what's there. Uh they're important for SEO. Well

ststructured page content is important for Google and other search engines to highly rank your page. Uh and also for them to scrape your site and feed it to AI. So yay. Uh heading is also one of the most common types of accessibility problems that we see with client sites and usually one of the most easiest to solve. So I'm giving a presentation about it. What are some

of those common accessibility pitfalls? Um, simple one. Sometimes there's more than one H1 tag on the page. Uh, according to the web specification, there can only be one H1 tag on the page. The documentation isn't clear about whether the H1 should be the site name because that's like the highest level thing or the page title. And I don't think it really matters, but you have to choose

one or the other. Uh, I used to do site name, but you know, I switched to using page title because that really is the most important thing on the page. So, and I think that's what Drupal uses by default. So, stick with that. Um, probably the second most common problem is skip levels. You look at a page and there might be some H2s or might just be

the H1 and it jumps down a level to the H4. Uh, not exactly ideal when you're trying to scan through the headings, especially with a screen reader and understand what the structure of the page is. Sometimes, especially if you've got, you know, your wizzywig not configured properly, you've got other HTML elements which are styled like headings. Uh, someone goes in and makes the makes the text big

and bold and colored, uh, but they don't use heading tags, so it's not actually a heading. So, it's not helpful for anyone with screen readers. Sometimes when you're editing the content, you might delete the text of a heading, but accidentally leave the heading tag, which is not ideal because it leaves a big unsightly gap in your page. Uh, and also again not great for screen readers for

them to be going down the page and reach a heading where nothing. Sometimes heading text is too long. Uh, kind of rambles on or it's not descriptive. Lots of times site uh editors or or content people are trying to play koi and and and and give you a give you a teaser but not really describe what's in the in the content. It's more of a problem with

page titles and headings, but but try to be direct and summarize the content. Uh yeah, and then and then uh a really big one, especially from a design perspective, is missing headings. Lots of times designers will omit a heading in their designs. If a section is visually distinct, they sort of assume that, oh, everyone knows what this looks like, so we don't need to put a heading.

Uh, one example would be if you have a section with a bunch of like calendar items. Someone seeing the page would be like, "Oh, this is this is the events section." There might be a banner that's like a call out to like go do something. Uh, and visually you see like, "Oh, it's a big big banner." But without a heading, there's really nothing for a screen reader

to land on. And if they do get there, they're not sure it's a whole separate section. And uh, menus is often another one that people miss. Uh, menus should be wrapped in nav elements and nav elements should have headings so that when you're navigating through the page, it will announce what the purpose of a menu is to any screen reader users. So, what makes a well-designed heading?

Well, obviously they stand out from the body text, and you can do that with size, weight, font, color, um, or style, italics. Uh, maybe don't go too crazy with those. Usually two or three different things about the headers is fine from the body text. Like maybe make it big and bold or or red in another font. Uh, you want to make sure that there's a visual hierarchy

to your headings that they, you know, start off big and then get smaller as they go down the levels. Uh, you want them to be distinct and easily able to tell apart from each other. uh so you know you know which one is a higher heading level and which one's a lower but they shouldn't be so distinct to be confusing. You want consistency whenever possible. The same

heading tag should look the same throughout the site whenever possible like uh you know you don't want it to change between different pages or change in different components or content types. And you want your headings to be legible at all screen sizes. Now, when you're dealing with designs that you might get from some designers, uh you might deal with some less than less than ideal situations, uh

where you might need to bend those rules a little bit. Uh often, even though you're trying to keep your heading levels consistent, you might need some variations like, you know, one common one is you might have uh H3 tags where if they're in a card, uh it's smaller text because it has to fit in a little tiny box. But if it's in the page content and has

more room and could be slightly larger. Uh again, like I said, designers love to leave off those those heading tags for for sections that they think are visually distinct. Uh you should still include them for screen readers even if they don't want them visually. And you could do that and then add a visually hidden class to hide them from site, but they're still available for screen readers.

Often sometimes there's a mismatch between the visual and semantic needs. Uh for example, if you have a sidebar with a menu in it, uh it might be an H2 as it falls in the in the structure of the page, but an H2 would be giant in the sidebar. So the designer will style it like an H3. Uh in that case, don't use an H3 tag. You want

to take your H2 tag and style it as an H3. So you think about that when building your theme. Uh, usually there's responsive text sizes. Uh, designers love putting a a mobile text size and a and a uh desktop text size. that's good for things like headings. You might have a hero on your page with really big text and if you know you make the screen smaller,

it just wouldn't fit on the screen. It's less good for smaller text on your page. um when you're moving from a desktop to a smaller screen, making the text even smaller on top of that uh isn't isn't great for people seeing it. I know there's less space to deal with, but you still want to be visible and have an adequate text size. So maybe body text and

lower headings don't get smaller on mobile. Um another thing designers love to do, they love to put bold or like colored text in the middle of headings. Um, it's easy enough to implement if you plan in advance. If for your your heading fields, you use a filtered text format rather than just plain text. Easy enough to add a bold a bold tag there. Uh, but you have

to plan ahead and it's not great for things like page titles, uh, H1 tags. Really hard in Drupal to to add those. You usually have to have a workaround where you put brackets around the bold thing. And then the other thing we're going to talk about are section tags. So in HTML 5, uh, introduce some tags that are semantically descriptive of the different parts of your content.

There's an article tag which wraps around your piece of content or sometimes the teaser of your content and sometimes items in your media library for some reason. Uh, this section aside header and footer tags define the sections within that article and those depend on where in the content that they fall. uh if it's at the beginning and contains some meta tags. So that might be the header.

Uh if it's at the bottom, it might be like also read this. It might be a footer. If it's on the side with a menu, it can be an aside like a sidebar. Uh but by default, start off with a section tag. Uh there's no visual styling like browsers don't render these tags any different. Um they're just like divs in terms of rendering, but they make great

targets for CSS. So when you're targeting sections within your content like an aside, you can use that instead of like using a div with a sidebar ID or something like that. So great for targeting. Uh unfortunately screen readers don't really announce them either, at least not yet. Uh which is a shame because as I said, they do provide good context into the content that you're reading. So

how do you build your Drupal sites uh for for proper sections and headings? Well, uh, the job of a content management system is to manage the content structure or manage the content and the structure. Uh, if you set up the editing interface, right, it can really empower users to get those headings in and and do it right. Uh, whenever possible, you can enforce heading rules and actually

force users to enter headings or force them to be in sections on the page. Ideally, you should automate things whenever possible so users don't have to think about the heading levels and Drupal will just add them the appropriate areas. Uh there's a bunch of different ways obviously with everything in Drupal to to implement things. Uh you could do like different page structures, configuration, contrib modules and then

in your custom theme. Uh and we're going to discuss six different methods to to manage sections and headings in Drupal. And now each method obviously has its pros and cons. Uh most of them most of them can work together or you can use them separately. All right, method one, CK editor and and formatted text fields. Uh, obviously the simplest way to create a document with text and

headings is is a text field. Uh, when you install Drupal by default with a standard profile, it'll create a uh a page content type and an article content type. And each of those will have a body and that will have CK editor and headings enabled. Uh it's easy and intuitive for your users. It's just like a word processor. They just sit down and start typing some text

and make some Uh the downside is is that relies on those editors to do proper heading levels to include things as headings and and you know get the structure right. Uh, obviously a wizzywig is not great if you want different sections of your content to have different styles or layouts or or look like different And it's not good for structured data. I'm sure everyone has had a

a client or someone where they've where they've created an event calendar but just use basic pages. So on every single page they have to put location, time, like whatever else like that. And it's really hard for them to do it exactly the same on every page and make it uniform. So, not great for them to be entering that sort of thing into the Wizzywig, but if you

configure your Wizzywig properly, uh it can really it can really help your users. So, we're going to talk about that. Um so, when you go to the text format in your in your site uh you can obviously enable CK editor for some of your your text formats. uh and it gives you a little section of that uh page and it's on the on the slide here where

you select what goes in the CK editor toolbar. There is a a heading which is called heading uh widget plugin uh that creates a little select drop down. So when you have text selected or you're on a line in the document, you can just drop that down and switch from normal text to one of the heading levels. It's really easy. Um, I suggest moving it, dragging it

over to the front of the toolbar because you want to make sure that users encounter that and see that it exists and so they aren't just reaching for that bold button and doing not headings. Um, when you add the heading plugin to the toolbar, it also enables a configuration pane that allows you to select which heading levels are enabled. Uh, I think out of the box that

it disables heading one tags, which is great because there should only be one heading one tag and usually that's added by the page title block. You might also considering uh disabling the heading two uh tags if this is a text format for a for fields that are going to go inside of a section. And you know, the different ways we add that we'll discuss later. Not as

important if you just have the big body body field. All right. Uh while while you're there configuring the CK editor plugins, uh uh maybe don't use the text alignment plugin. Um heading should be uniform as possible so you can scan down the page and if they're jumping back and forth, uh it makes it hard. Also, it can uh if you if you set, you know, the text

alignment, it can interfere if the user goes to translate the page to a different language. It might have text direction that goes the other way. And unfortunately, last time I checked, when you choose the text alignment left or right, it actually uses in the CSS left and right rather than start and end. So that means if you translate your English text to Arabic or something that moves

from the right to left, most of most of the text go and it'll switch the orientation or switch the alignment, but anything you specified that it's left or right, it'll just stay like that. So hopefully hopefully they switch the start and end and then this won't be a big of a problem. But for the time being, I I wouldn't enable it, especially on headings. Um, ideally disable

the image alignment as well. Uh people really love aligning their images left and right, but those can interfere with lots of things, but including headings. They can squash your headings, they can push them over. Um best just not to do that. Um most text formats, uh you want to enable that limit allowed HTML tags to filter. you know, it is a security risk to have like non-admin

users just adding random HTML and scripts and, you know, tracking cookies and things like that to the page content. Uh, both annoying, invades people's security and also creates a a risk of malware. Also, you really just want a uniform style and layout across the site and if people are adding random HTML, it does not help with that. But, you know, removing removing the ability to add style

tags and style attributes keeps editors specifically from doing that thing where they make regular text looks like headings. Like if they can go to a div and they can say like, you know, make the font size this and make it bold and colored, they'll do that instead of the actual heading tags. Uh, you don't really have to configure this now because when you set up CK editor

and drag the plugins, it sort of takes control over the loud HTML tags, which is both easier and frustrating if you want something slightly different. another another thing that lots of people don't know about with CK editor and Drupal, uh, you can pass it a stylesheet. uh you can make the headings inside of your wizzywig look exactly the same as the headings uh when you're looking at

the site. That reduces a lot of disorientation when users are adding the site and choosing their heading levels and they go to the front end and things look completely different. So having them match up is really helpful for site editors. Uh and it's really easy to add starting in Drupal 9. Uh there is as you can see here there is a a a key that you add

to your uh theme.info.yaml YAML file that is CKeditor 5-stylesheets and you just pass it a a relative URL to the theme. Uh you can create a stylesheet just for CK editor with just like the headings, whatever you want like that, but often we'll just pass like the entire compiled theme CSS to it. Most of it just doesn't apply. It's all in an iframe in the in the

in the CK editor, so it doesn't really affect things. So it's pretty easy. just throw your stylesheet in Also, uh, one module that we that we add for a lot of user uh, sites that helps is the editorially module. You definitely install this if there's a lot of wizzywig fields. Uh, the way it works is it flags issues when you're browsing the site. It has a little

little bug that's in the lower left that counts the number of accessibility problems that you have on your page. So it'll flag when things are wrong. In addition to running on the front end, it'll also run on the content edit forms and it integrates with CK editors. So it'll flag heading issues as your user is creating them which is very helpful and hopefully they fix them all

before hitting you know submit publish. All right. Okay. That's OCK error. Method two for for site building for sections and headings is uh field groups. So there is a module called the field group module and it groups fields into helpful in many cases but for our case it can be used to create sections of related content on your page and it'll automate the creation of the markup

so it can be a proper section with a when you're creating a when you're creating a field group on the edit form. form. Uh you can group a bunch of closely related uh fields together or kind of like this uh it could also be a grabag of metadata about your current node. Um this example we've got a a basics field group and this is for a school.

So inside a school type, school code, grades, and estimated enrollment. Um it gives more structure to the edit form also and helps users find the place that they're looking for. You can create them both on the front end and on the edit form. And usually it's best to do exactly the same on both. So again, you really want your users to be able to switch back and

forth between the front end view and the edit form and things to be exactly in the same place or labeled the same way. So now when you're configuring your field group for display, you have a lot of options that help you with your headings and your sections. Uh this is the the configuration form or the top of it. Um you have your field group label where you

can write what the field group is about. And then there is a uh element field which allows you to specify a wrapper element. So you can do something like enter header or section. below that there is a a yes or no select list uh for show label and you know so you can show that label at the top as a header uh at the there's a label

element that field that appears if you select yes or you could select something like H2 to make it an H2 header and since field groups can be nested in other field groups you could also specify by H3 if it's a a subsection. This is the bottom part of that long Uh the label element can have an HTML class as well. And that's and that's great if you

have one of those things where you need to visually hide a heading that shouldn't appear thanks to the designers. Um that's helpful. And also there are ID and CSS classes that you can add. And that makes styling your field group as a section on the page really easy because you can get styles and layout to apply to to a field group. Uh the output here's the the

front end example of uh that school basic fields. Uh you can see how you know it's it has a class so it's been styled as a grid of tiles. Magic. Okay. Third third site building method for for for sections and headings twig. And now this warning you is is probably the most technical and code oriented option. So we're going to have some we're going to have some

twig files to look at which is fun. Um, if you want to group a bunch of if you have a content type and you want to group a bunch of the fields together uh to make a section, you can do it in the in the field the node the node type HTML twig file. Like in this case, we have node-blogpost-full.html.wig. Uh, you can use one of the

HTML 5 tags to define a section. You can see here we have an aside with an ID of categories. You can add a heading if you're if you're specifying a section inside of a twig file. You usually have like a hard-coded heading. It should always be. And so here we have this an H2 with that with the text categories and related content. Uh if you're if your

site is going to be translated, make sure to wrap that string in uh in quotes and pass it to the T filter uh which will which will translate that. Uh but yeah, but then you then you output your desired fields. So we have like content field blog category, content field subject areas, content field filmmakers, and content. Films. So all of these fields will appear in the side

uh that's labeled headed heading of Um just note that if you do this and you are manually outputting some of your fields, uh you don't want them to appear again. So when you're printing the rest of your content, you probably want to use a without filter to hide them from being displayed again. Uh in addition to grouping fields together in your in your node template, uh you

can also turn individual fields into sections. Uh on the on the right, you see in the code we have a section up there called featured review and it creates a section out of uh the field reviews uh field. Um, note that if you're doing this, you probably want to do an if statement that checks if there's a value for that field because you don't want a blank

section. So, it's always good to check and you know, you have to go if content field reviews and then dot0ero to check that there is a a first item and there won't be if there isn't. at the bottom you can see a section that was created rather than one of those usual HTML 5 things we talk is a is a details element and a details element also

is kind of an accordion. So you can use that to create a collapsible section on your site. Uh you can see in the summary which is the clickable title we have an H2 tag called synopsis. Um, one of the things that you can't do in field group is that if you select a details element as your display, it doesn't show you that heading element. So, there's no

way to put an H2 into the summary. So, if you want a collapsible section, this is the best way to do it. Um, traditionally, there was some advice, you might still see some advice online about not putting headings inside of summary tags inside of details elements. Uh, I think Internet Explorer maybe some brow uh browsers had trouble uh targeting those when you're using screen readers. Uh, but

as far as I know, I think it's all fixed. So, you're perfectly fine to use headings within details summaries. Now, um, if you want a field to be a section, no matter what content type it appears in, you can also put your section tags inside of the field templates. So on the on the right you can see we have field-field resource files html.wig and you can just

copy your field.html twig and change the div that wraps the rounder from a div to a section tag uh and you can wrap your uh the label for it in in an H2 tag. one thing this also helps doing is a lot of times you might want a different heading output to the user than is on the edit form because sometimes the edit it's not clear on

the edit form. Anyway, you could also hardcode it here so that there's independent from what the field is called inside of the edit form. if you do it if you do it like this, the one problem is is you keep copying that field.html.twig twig. Every time you need a new field to be a section, you end up with a lot of copies of the same markup. So

in our themes, what we do is we take advantage of of some twig variables. Uh you can see this is the same the same sort of default uh field markup, but we have two variables field element and label element. Um those are output using null coallesing operators. So if there is a value in them, it'll display it. And if there's not, it'll just use the default divs.

So by default, your fields will just have divs wrapped around both the the whole field and the the heading. Um, but what that lets you do is let you extend the default template and change it. So on the lower there, you can see that we have field field reviews and it extends field.html.wig wig and it sets the field element to section and it sets the label element

to H2. So that when you want to turn any one of your fields into a section with a heading, all you have to do is write three lines of All right. Uh another big thing where you know Twig templates help control uh headings uh is in navigation elements. Uh you don't have to do it from scratch. Alo has actually a really great example of a menu block

template. it does it does a bunch of great things. It uses a block title as the heading. Uh you can see there block configuration label is is the block title. Um unlike other block titles, if you select do not display the heading, it adds the markup anyway and then just visually hides it. And that makes sure that there is always a heading tag uh for every nav

element. It might be not the best one because it's not clear in the block placement configuration that if you click don't show the heading that it still will show whatever you put as the administration label. But uh it it is something uh another great thing is it automatically obviously at the top it creates a setting id or heading id equals the uh the attributes ID which is

the ID of the menu u-ash menu and what that does is it applies that to the heading element and then it can use the area labeled by attribute to say that this nav element is labeled by this heading. So when you arrive there in a screen reader, the screen reader knows to announce that it's a nav element or menu and that and it'll say whatever the heading

is. One thing that the the the Olivero uh block does that maybe you might want to undo is a little bit there at the top where it says set attribute ro navigation. Now nav elements because they're nav elements already have the role of as part of their whole thing. So you don't need to add a separate role equals It doesn't affect the users um it doesn't really

affect the users uh at all. Uh browsers uh won't do anything any different. Screeners won't do anything different. Uh what we'll do is uh the the screen reader uh I'm sorry accessibility scanners might complain uh and flag it as an issue that there's a duplicate role even though again it doesn't matter. Accessibility scanners can be really annoying uh like that. So if you don't want extra work

for yourself just get get rid of that RO navigation. All right. Method four, paragraphs. All right. So, uh, paragraphs module. It defines an entity type that works just like content types with bundles and fields. Unlike content types, it doesn't have a page of its own. Uh, we we embed those paragraphs within other entities like nose using entity reference revision fields. when you're when you're adding there's just

a there's a little button say paragraphs so you don't have to worry about that's what it is on the on the add field form. Uh it's really good for grouping fields just like with field groups. Uh but it does it more of in a relational matter so you can have multiple copies of the same group of fields or you can have arbitrary sometimes you have it and

sometimes you don't. Uh it it's also that makes it great for defining content sections on your page. You can create paragraph types for the different types of section. Um when you create section paragraphs uh with headings uh they can provide the general structure of your page. So someone can go and add a bunch of sections to the page with headings. Um obviously the different paragraph types can

have different fields and layouts and styles. And so it kind of works like a component library where the the the site editor can choose between a bunch of different section types and they'll get that. Um this kind of works best for layer cake designs which is basically a bunch of horizontal, you know, a bunch of horizontal sections and not things going back and forth and side to

side. Uh but that's the way it it works for screen readers and mobile users as well. So, it's kind of a better way to to plan it rather than sort of arbitrary placement on the page. All right. Um, in order to put paragraphs on your page, you add a field uh uh for paragraph types, you can specify which paragraph types are available for adding to your to

your field. Uh, so in this case, we have a field. It's called content sections. And when you go to the add at the bottom, you see add section text block, add section cards, add section. So you just choose the section to be put in the section field. Uh now these are all editable on the node edit form just along with the other fields, the node fields. So

to the user, they're just more fields. They don't have to worry about uh going to a separate like layout tab or some editing interface that's separate just for for the layout. uh they can just edit it on the edit form as with the rest of the content. Uh and since it uses the node revision field uh the node yeah um the entity reference revision field it supports

revisions and also translations. Uh that means it can be it translated along with other content unlike some other newer layout things. Um you can have multiple paragraph fields. So if you do want different regions of your content like you want the main content, you want maybe some footer, some aside, some header, you can actually create separate section fields. So in this example, we have the page sections

which is the main content sections and also footer sections where you might put callout cards for for other related content. uh it sort of works works works like you can you get it to work like the block placement but without you know the separate admin interface and just within the content of the page. so when you're creating your paragraphs for sections uh you can add a heading

field to every every section of your that's added to the page. And ideally uh you could make it required. So when these section paragraphs are output, it'll have them as an H2. So every section on your page has a H2 heading. Again, you've got that problem where sometimes they they think the heading is unsightly or unneeded. So for some clients, we add a a visually hide title

checkbox. And if they click that, it just adds the visually hidden class and it'll hide the hide the heading visually, but it's still available for screen readers and it's still required. So they still have to add something. Even if they don't want to see it, they still have to add it. I I really force site editors to do a lot of things they don't want to, and

in the end, they end up appreciating it, I think. But all right. Uh paragraphs, uh you can nest them. Paragraphs themselves can have paragraph fields. That's good. So if you have something like a section for cards, uh inside of it, you can have individual card items. um those those items be configured just like the sections uh with a heading field a required heading field but when they're

output they're output as an H3 instead of an H2. Uh I mean the good part about that is is is unlike some other layout systems the the site editor doesn't need to know what heading levels are and specify them. Uh they just add content to the edit form and it'll appear on the page with the right heading levels. Um, I try to use a a naming convention

when when creating these section paragraphs because often you have some other paragraphs that aren't sections and if you just sort of start them off with section then they'll all appear together on the on the admin edit form or the admin paragraph management table. Um, and then also we can use that to help determine heading levels when output. So this is the paragraphs the html.twig twig file that

we have in our uh in our themes and we've got a element variable and we're setting that based on if the paragraph bundle the the paragraph type the machine name starts with section but it's not an item doesn't end with item then you know that it is a section of the page so it chooses a section uh element to wrap the whole thing in on the bottom

here you can have a field field heading. HTML or you can specify that's if you have a field heading for nodes, you can specify it's for paragraphs. Uh that looks to see if the the bundle for the the paragraph the paragraph machine name ends in item and if so it knows that it should be in H3 otherwise it'll default to H2. So what this does is if

you have this, you can create new paragraphs for your sections. And as long as you put section at the beginning of the machine name, it knows that it should be wrapped in section tags and put in H2. So you don't need to have individual templates for your different paragraph types. It handles it automatically just based on what you put the machine name. Uh, one of one of

the best things that paragraph does that is very rarely used is paragraphs offer a preview. So on the edit form you can see a preview of the paragraphs uh while you're editing it. So when you load up the edit form there's the paragraphs field and inside is previews of it. Uh the reason that sometimes it's not used uh the reason it's not used is because by default

node edit forms are in the admin theme and since the layout marker the CSS that does the layout and the styles for your paragraphs is in the front-end theme if you usually set to preview it's just a bunch of random content without any sort of formatting. So it's not a great preview. however, in the in the theme settings, there's a little check box that says you display

use front-end theme for nodeedit forms. So, that means that nodeedit forms can use the front-end theme. Um, you have to make sure to to style all of the the field uh types that the edit form will use in your theme, but then you get an edit interface that looks like the front-end interface, and it's less uh jarring for editors to switch between that and the edit form.

Um, but the benefit of that is then you have all your CSS necessary for rendering your your paragraph previews as actual previews. Um, that'll that'll make your edit form kind of work like an edit in place editor where you switch the edit tab and it it'll show your page content uh but it'll have like an edit button where you can edit each thing and it'll open it

up and you can edit the fields. Um, this example on the right of a of a site we just set up. Uh we're working on a module that sort of cleans up this anytime you have a paragraph field like other things that has weights and reordering it. So it'll wrap it in a table with the draggy droppies and the show weights. Um coming up with a a

module to sort of hide that chrome to make it look like a clean preview. So um I think that's working really well for the users because it really does look like the page except for having these edit buttons. Um, the reason we're able to do that is paragraph module also provides a drag and drop interface for reordering things. Uh, people don't usually know about it. It's it's

hidden in the in the three dots at the top of your paragraphs field. Uh, but you can edit the drag and drop and it'll let you drag and drop all the different sections uh to reorder them and also the items within sections. And then also there's magic where you can actually drag items from one section to another section. So, if you have two different card sections and

you want the card to move, you can just drag one to the other and it actually does like checking to make sure that the sub paragraph can go into the parent paragraph, but it's all very good. Um, one caveat, the the drag and drop interface does not work for keyboard right now. Uh, so that's one reason you might not be able to hide the chrome on the

the usual drag and drop interface if you have keyboard users. Uh, hopefully they fix that. Um I think they think drag and drop is only mouse but really great if you had a keyboard and you could hit spacebar and you know drag it up and down with your arrow keys. Yeah. So that's so that's paragraph method five layout builder. Uh the layout layout builder and I realize

they're almost running out of time so I got to move fast here. All right. uh layout builder. Uh the initiative was started in 2016. It was included in Drupal 8.7 in 2019. Uh like most core initiatives, we decided that we're going to make this thing and it's going to go in core no matter what, even if it's not actually fully baked. So it's uh it tried to

solve the problem. Users wanted to drag and drop content all over the page. It's not great, but it's popular because it's the only option for doing that in Drupal Core. Um the heading structure is one of its biggest problems. Um, it's very easy to add block titles. There's a configuration block. You put a title and you put display title and then it adds as an H2 to

your block. And it's great if all your blocks on the page are H2s. Unfortunately, uh, if you're using layout builder, that's cuz you want sections that have multiple columns. So, there's no way to add an H2 to the section that contains those blocks. And there's no way to get the block titles to display H3s instead of H2s. one workaround is add a section that just has an

H2 element above your thing. Uh, which works on the front end, but on the edit form, it doesn't reinforce the fact that each section should have its own heading. Uh, Calamooi came up with a module. It's called layout builder section configuration. And what it just does is it uh uses to you can use it to display section titles for your headings for your I'll just go to

the next basically it opens up a configuration thing for your section where it adds sort of the same checkbox which is show title to end users where it outputs your administrative label as an H2 heading for your section. Uh it adds other stuff where you can select what level title wrapper usually H2 in this case and a bunch of sort of position color things that you don't

really need but it does have the a classes uh field so you can add the visually hidden if you want your section to be visually title heading to be visually hidden. Um and then if you create custom block types uh you can have a a header or a heading field that'll put the H3 into the individual blocks that you add to layout builder. So that sort of

solves the page structure in layout builder to an acceptable level. All right, method six, the new one, canvas, uh it's layout system, formerly known as experience builder, uh part of the starshot initiative. It was included in Drupal CMS uh 2.0 and really it's kind of just like the second version of layout builder uh with with a lot of improvements and how it works. They have a lot

more plans for it. So, you know, get ready to unleash your creativity with uh AI integration. Uh canvas actually actually pretty good for content structure. Uh the new layout panel reinforces that the content on the page is linear uh just like it's experienced on mobile and in screen readers. So, that is fantastic. Uh it's got these heading components that you add to the containers. Uh so it's

really easy to add headings even though it doesn't really enforce that you have to add it. Um and the integration with single directory components can make things even more accessible. Uh you can you can uh configure those heading components. Uh it has you can easily choose the heading level by entering a number. Not ideal but it works. Uh it has a style drop down to style your

headings different ways if you want to do that. It's better than providing like color size dropdowns. Uh it has alignment and margin which you don't really want to mess with but it's there and also it has the modifier class so you can visually hide it if needed. Uh now single directory components let you specify components that go into your canvas options. Um it can be used in

v single directory components used in a variet including being placed in canvas. They live in a single directory with the twig and the uh the JS and CSS all together. There's nothing stopping you from just doing that in your theme already. You don't need single directory components to group those files together as I've been saying for years. Uh but this helps. It adds a YAML file that

lets you specify what kind of content that is put into it, which is helpful. and you can see that some of the things that you can add in the default installation of of Drupal CMS 2.0, O they've got like a CTA uh element that you can add a CTA component and inside of that it has settings for title and when you output it it puts that title

into a heading tag automatically. So this is a way that instead of just generally putting container and and columns that you can actually specify section types to be placed on the page with proper heading structures. Uh it also it also allows nested components. Uh so when you're when when you're making single directory components, not yet, but soon you will be able to specify what goes into it.

So if you have a section cards component, you can specify that it has a a slot and inside of it you can put individual card components. Those those will work with tags. Uh hopefully um there's a lot of conversation about the different ways to so one one thing of confusion right now is there's a lot of when you go and install canvas, there's a lot of components

that are that are provided by like the navigation module and stuff like that that you don't really want users placing on the page. So if you go to admin appearance component, you can actually go through the different components that have been created and disable those. And then if you disable them, they shouldn't show up on canvas and they shouldn't be available for the users to add if

they shouldn't be doing it. And hopefully that will reduce uh confusion. there's still a lot up in the air about how canvas will work. uh some people are in the in the in the thing saying there should be no restrictions on anything being placed anywhere and you know kind of a sprung anarchist contingent. Um I encourage people to go in those issue cues and and advocate for

canvas to to support you know well ststructured uh pages with restrictions on what can be placed there and what can be placed within them and required headings and things like that. So um method seven there might be things I miss. So, if I have missed some way that you add sections and headings to your site, please come up and let me know. Not sure if we have

time for questions, but I'm here and available to answer any unless anyone has any pressing right So, that is the end. Thank you. Um, my my email address is here at the mikemaloon.com if you want to email me any questions about this or or send me any suggestions on on other ways to do things. And this is that that QR code thing that they want you to

fill out. So, all right. Thank you.