 So my name is Amy June and you are in markdown in minutes and there is a QR code there if you want to follow along there's a link to my slide deck and The only reason I linked to the slide deck really is because there's some resources at the end and then I have a get lab Repository and it's an easier way to get to the get lab repository from the slide deck So some housekeeping, you know, we're in Hopin. I don't think captions are enabled So I'm gonna do a little trick right now and enable captions and I'm gonna show y'all how to do it because it's pretty cool on Google slides if you like hover over this and you do captions you can like select your text size, which usually I put it large and then Text size large and I put the position at the top and then you toggle them on and now I have captions at the top And the reason I put them at the top is because when the session is recorded the YouTube now will put captions at the bottom and The captions that I'm displaying up above are now open captions, which means you can't turn them on and off So I put them at the top so they don't like clash with the with the YouTube captions There are images in my slide deck, but most of them are decorative. So I won't be explaining them for brevity and The views and opinions expressed by me here today are my own Amy June and are not connected to my company the WordPress community or WordCamp Montreal So with that some of you may know me. I'm Amy June. I work in the WordCamp community Doing some diversity and inclusion stuff, but mostly I'm in the Drupal community. I work at the Linux Foundation I help build exams and certifications for the Linux Foundation For emerging technologies and then there's my LinkedIn information and you can find me on Mastron This is spot He's really cute. He's my cat and I like to blame any typos on him so him running across the keyboard But he really is a good cat and he loves everyone. So that's spot If you want to follow along when I do the demo if you don't have a editor excuse me, you can do try discord.org and Open a free account and open a little window, but you don't really need to necessarily Type out what I do because I'm going to do a demo where I show the markdown and then I show the rendered stuff So don't feel obligated to open an account on discord So why markdown? plain text files, you know the dot txt files Don't really allow for formatting like headings or subheadings or even things like bolding italics underlining lists And when you have a markdown file a dot md file It formats it for you. So really a markdown file is Kind of like a cross between a text file and a markup language like HTML, but unlike HTML, they are very human readable And markdown is simple. It's intuitive and it's portable And can be converted to HTML or PDF or other formats using various tools and platforms And what I mean by portable is you can take it from one instance to another and not worry about It not working You can be converted to HTML, which is nice and it's accessible. It can be converted to PDF But in this day and age, we should not be using PDFs, but that's a whole nother talk on accessibility So think of using markdown like using an editor without the whizzy wig buttons You can add formatting. It's used from project to project and then When I say that markdown is more accessible what I mean is for people who maybe you know have a palsy or don't have a Mouse they do not have to do the extra Effort of like highlighting text and then pushing a whizzy wig button. It's just a couple of keystrokes on their keyboard So it's accessible in the programming sense, too This is a slide left over from a Drupal deck, but if you use CK editor 5 the plugins even in WordPress Markdown is now in CK editor 5. So that's like a really nice bonus And to iterate you can use markdown on any platform or operating systems Since there are dozens of like really good markdown editors for all platforms. This includes Linux if you use a Mac if you use Windows or if you're just like entering content on the web through your through your WordPress editor And it's a really great tool for non programming types and technical writers to write text without having to rely on knowing HTML And Markdown kind of gets rid of all the distractions of a formatting toolbar, you know because you don't have to do those mouse clicks anymore You can focus on your writing without Lifting your fingers off the keyboard. It really gives you more control over your editor's experience and if you Contribute to technical writing or maybe a technical publication editors actually prefer You to submit your stuff and markdown because when you submit your stuff in a Google doc You know when you copy and paste it you get all those weird spans and stuff And then if you copy and paste and without formatting then you lose all the formatting so Think about that when you're you know submitting an article like open source net or or any any sort of Medium like that. So applying the basics to markdown We start with an MD file like I said Not a text file because the MD file lets your editor know that you're gonna render it in markdown And then you really kind of have to know your flavor of mark Excuse me, I'm gonna take a drink so when I say know your flavor to really help like wrap your head around what The concept of markdown flavors are it might help to think of them as like language dialects Get hub has its own markdown get lab has some additional things and then depending on your editor, you know some things don't cross over and Everyone has their own favorite markdown editor My best advice is to take your time and find out which one works for you and Markdown syntax again is designed to to be readable and unobtrusive So the text in the markdown files can be read even if it's rendered and we'll we'll look at that more when I open the get lab stuff So there are all There's a whole bunch of markdown editors and I'm an open source fan So I have some listed here. My favorite markdown editor is VS Codium which is a little different than VS code because VS code actually isn't open source. It tracks you so VS Codium is my favorite one because you can have you can be writing on one side and have a window that renders it On the other side, so it makes it really easy like to see what it's gonna look like And then there's some not so cool editors meaning that they are Not open source obsidian actually is my favorite markdown editor But I can't say that because it's not open source obsidian is like super cool. If you haven't seen it, please explore it It's very dynamic. You can like open files from, you know In in very dynamic ways, but again, that's another talk, but not so cool editors And what are we gonna talk about today? We're gonna like I'm gonna close this slide deck in a second and we're gonna go into a get lab instance and we're gonna like look at How to do some inline formatting like bold and italics and strikes through we're gonna learn how to make our File accessible by adding headings. We're gonna look at how to create different kinds of lists block quotes horizontal rules And then a couple of these things are Specific to get lab so we'll do the slow charts and diagrams and task lists and tables and they are super cool and Before I close my deck. I just want to remind everyone in light of a prominent community sponsor in the WordPress community Their decision to host Hate groups I want to remind people just to be mindful of your hosting platform's accessible use policy and make sure that the platform prohibits Self-hosting from designated hate groups and when there's adequate evidence that's been provided for such a designation But anyway, we will mosey to the demo There's a QR code and a bitly link here. Oh, no, this is a get lab link So get lab comm Volkswagen chick and again, you don't have to go there But it's Volkswagen chick and it's marked down hyphen in hyphen minutes But you can just watch my screen and you'll be perfectly fine so with that I will Stop presenting and Go to my get lab instance again. It's you know Get lab Volkswagen chick markdown in minutes and what this is is this is a get lab repository that That I've created specifically for this talk It's a work in progress I do change it from time to time We have like this is the read me file when you first like if you're not familiar with how get hub or get lab works the first thing you do is create a Read me and so my read me as you see here is written in markdown And you sort of go to the read me automatically by default. So this is written in markdown. You can see like I have a Title I have some horizontal rules. I have a list. I have links And this is the this is the default Template for a Drupal read me like for their contributed modules And I have some open so all of these are separate files just to like kind of you know separate things out The first thing we'll look at is inline formatting examples. So we're going to look at how to format italics bolds strike-throughs and block quotes and It looks like there's a little mistake here, but we'll forgive. We'll forgive me for that. Oh It's spotty's fault because he does he does he does the programming and get lab to So if you look here, you know, I have italics To to add italics in a markdown file You add one a strict or underscore before or after the word or phrase. So if we like toggle over to the code We can see that there's an a strict on either side or there's an Underscore so add one a strict or underscore before or after the word or phrase with no space between the word or character So we'll toggle back and see that Both of those render the same in their italics The next one is bold and we're going to edit this I think because that's not the way it's supposed to look You're going to add two asterisks or underscores before or after the word or phrase with no space So for italics we did one but for bold we do two. So if we toggle over There's a space right there. So this is a good troubleshooting exercise actually so Again, it's the same as italic but with two asterisks or two underscores Before and after the phrase with no space between the word or character So we see here that I have a space. So if we look back that didn't render Correctly, so we'll just go in there and edit that real quick Oops, no not that. Okay. We're going to edit in a single file We'll go in there and we'll remove that space And then when we hit save We can see that now it rendered correctly. So some of these things like if you think like Like if it doesn't get right, it's either because you added an extra space or maybe you you you didn't have a space Strike through is two tilde's before and after a word or phrase with no space in between So we have the strike through so if we toggle to the code You can see that I have two tilde's the tilde is above the back tick On on american keyboard in the on the left hand side So we have a strike through two tilde's before and after And then we might as well look at block quotes right now The code so if you want to create a block quote, you add a carrot in front of the paragraph What is that a Greater than sign so I have I love drupal with a character and a space so if we go back to The rendered file We can see that I created a block quote with just adding that character. So we'll look just one more time italics we have the The one asterisk before and after For bold we have two asterisks before and after strike through we have two tilde's before and after And then a block quote we have that carrot So the next kind of cool thing about Markdown is you can create headings and we all know Or should know that we use headings for accessibility and not for Formatting so what this does is it breaks up your page and and makes it Accessible to screen readers or people who scan or people who use assistive technology. So again headings are for um Are not for styling they're for like semantic markup so To create a heading you add hash Tags in front of the word or phrase. So we have like a heading one heading two a heading three a heading four and a heading five So we add hashtags. So if we look at the code Each heading heading one has one hashtag heading two has two hashtags and heading five has five hashtags Alternatively in get hub you can create a heading These look completely the same heading one and heading two We'll look at the code You can do heading one, you know, this is my heading and now what I did was I put equal signs All the way across and then to create a heading two you do hyphens all the way across But you only can do up to one or up to two headings So if you need like, you know, if you're doing a longer article or a read me or technical documentation And you need to break it down more The hashtags are the way to go, but if you just have one or two you can do it this way Horizontal rules are kind of cool. Here we have the code. It's simply three dashed lines So if we go to the code or to the rendered file and we look at it You can see I have three dashed lines and it created this horizontal rule across the bottom Code formatting So this is really important for accessibility. Sometimes what I'll see is I'll be looking at an article And uh, there'll be a image of code rather than Than uh actual code block And what that does is like say you're you know, you have this this this code that you want to share Well, the image isn't accessible people cannot copy and paste that So they would have to like go into your alternative text. Hopefully you used alternative text, you know, find it and copy it from there but if you Create the code in the text itself people can just simply copy and paste and not have to worry about it And there's two ways to do code formatting. There's what we call inline code where you have maybe you have code Inline with your with your sentences and there's also code blocks And depending on what markdown editor you use The code block renders a little bit differently Sometimes I've seen it like in the square and sometimes I've seen it shaded in like the inline But in a in a big block So if we look at The code To denote inline code you do a back Excuse me A back tick before and after without a space And then do a code block you start with three back ticks on one line Write what you want and then start a new line and do three back ticks So again, if we look at it, you know, this is one back tick before one back tick after And then for code block, we have three back ticks before new line Your code and then a new line and three back ticks again. Let's look at it Rendered you can see it's formatted two different ways Inline blow block and then a code block The next thing that is kind of cool are links, you know, we all love links And we need to make sure that they're formatted, right and in markdown. What's nice is it's a couple of Just keystrokes rather than like copy and pasting or copy and highlighting and then hitting that that editor button So To do that and it's really hard to see because this is rendered but the link text for like a pretty straightforward link You enclose it with square brackets And then you put the link in parentheses. So if we see here, we can see this says link text It's underlined when hovered here's Drupal camp Asheville. It's underlined and hovered And if we go and we look at the code I have link text that we saw remember that was highlighted Or under underlined when we hovered and it was a Hyperlink so we put the link text in parentheses and then we put the url and print or sorry the link text in brackets No space and then the link url in parentheses So remember that said link text and then we had one at the below it that said Drupal camp Asheville So again, we'll look back at it. It's the same thing You put the the link text that you want in the square brackets and then you put the url itself in parentheses To add a title to a link. What does that mean? So if I hover over this Drupal camp Asheville You can see that now I have a A title, you know when I hover over it it says Drupal camp Asheville's homepage. So how did I do that? Well in markdown We'll look at the code Here's my Drupal camp Asheville. Here's my parentheses pretty much the same as what we saw before But what we do is in that parentheses we have a space And then in quotes we have what we want our title to be so again We have our link text in square brackets We have our url immediately file following in parentheses And then if you want to add title text you have a space and then the quotes and it comes out Drupal camp Asheville While we're here and looking at code If you have a relative link say like you're linking within a repository or you're linking within the same website and you have that beginning hash You can do the same thing where you put the the link text in brackets And then what you can do is you can shorten that url and just have Uh The last part of it. So to make it more understandable. Let's look at it Here's a relative link within a repository. We did the same thing the link text and brackets the url in In quotes, but we didn't have to put The whole thing before it so you can see I have blob main lists Because it's in this repository when I go and click on it What's going to happen is when I go back to lists I'm going to open that in a new tab so you can see it goes Back to the original repository kind of cool email addresses you can render really quickly you It's real straightforward. You just put the the information you want in brackets. So here we have you know a website And then we have an email address. So if we look at that in In the code All we did was we put it in brackets and then if we look at it rendered again It it's you know, it just quickly turns the url into a link So you don't have to um like if if you don't need it to like like say Drupal camp Montre or sorry word camp Montreal or whatever you can just do the url and enclose that in brackets Um, which one do I want to do next let's do lists next because that's a pretty common thing in uh When we're writing technical documentation So there's ordered lists an unordered list an ordered list is numbered Where an I'm sorry an ordered list is numbered and an unlord unordered list is bullet points So to create an ordered list you add line items with numbers followed by periods and the Numbers do not have to be sequential So if we look at it here, I have number one number two number three number four And then here it's kind of says the same thing right number one number two number three number four but What's cool is if you look at the source code. I didn't have to number all of them I didn't have to like say your your documentation is super long on your item 54 And you can't remember what number you're on you can just do ones all the way down and it renders the same So again One two three four or one one one one Look at the rendered stuff. It's the same. So pretty pretty nifty shortcut Bullet lists, um These all kind of look the same To create an unordered list you add a dash An asterisk or a plus sign in front of the line items So these all look the same, but if we go and we look at the Code We can see that I did it a few different ways. I did a hyphen here an asterisk here and a plus sign and They render the same. They're the same html, but maybe maybe You have a favorite keystroke and it's easier for you to hit an asterisk than it is to hit a hyphen So again, it doesn't matter how you do it You just do a dash an asterisk or a plus sign with the space and then again for iteration When we look at it we have our bulleted lists So what's kind of cool with markdown is you can combine the two you can have an unordered list Within an ordered list. So this is it Rendered we have our list items right and then we have some bullets in here. So how did I do that? Look at the code We went down here. We did our little trick remember from up here where we didn't have to remember the numbers So we numbered all of them and then we did like a hanging indent where we Spaces not tabs we spaced to right underneath where the list started and then we did the same thing for our Unordered list so we have an ordered list and then to put a bullet point in an in an ordered list we Spaced all the way made a hanging indent and did our bullets So again, what's it look like? It is our ordered list and then we indented Four spaces because that was what was underneath and then we have our bulleted list. So that's really cool Um tasks lists are nice. Let's look at task lists There's tables there's footnotes and flow charts. Yeah, let's look at task lists first um You add bullets and then a set of brackets with a space in between and to complete a task list task list List you just simply, you know, uh do an x and then to strike out a task you add a tilde So you see here we have a completed task with a checkmark checkmark and then we have a strike through So what does that look like? So we go back and we have a bulleted list And then we have those brackets So the completed task we saw was a check has an x to strike out your task You have the tilde and then to have an incomplete task. You have an empty bracket So to look at that one more time Rendered we have A task list and the nice thing about task lists is It keeps the history So even though like the task is no longer applicable when you strike it through people can still see that in the history Again, you know, it just depends on how you fill in that space before a completed task as a x a strike through is Is a tilde And then we have drop downs which Maybe I shouldn't Teach people Because they're not accessible by nature, but they're really kind of cool. So I have this drop down here What is the best Drupal camp in the world? But and I click on it and then I have the answers right there. So if we look at the code we have details We have a summary which is our question and then we you know, you know Close the summary and then we have our answers answer one answer two answer three and then we closed out that details So that details in the summary is what pulls up that that That button so if we look at it rendered again You know, there's a drop down and then you can you know show and hide your answers not accessible But kind of cool um, the next one Let's do Flow charts So I am not a designer my perfectly themed website is craigslist Um, so when someone asks me to do a flow chart and I have to like open figma or draw something It's like super not convenient for me because it takes me like three hours to make a flow chart but If you work in get lab look how cool this is Um, and I think that you can do this in get hub in the last month that they they have this tool in two But I have my flow chart a to b b to c C to d and then we have a goes to d but b also goes to d and d goes to c So what does that look like as far as code goes? So you have to call up a library, which is the mermaid library So we did three back ticks and called the mermaid library We have a command called graph TD which is table data We have a colon and then I have a map of where I want everything to go So I have a to b b to c c to d b to c And then the second one I called that library again called graph table data and then with a colon or semi colon And I called my a to d b to d d to c So let's look at that again We have a goes to To d b also goes to d and then d goes directly to c And then just to kind of like like reinforce how straightforward it is. I'm going to make an edit so we can see that So, um, let's add something right here. So we're going to do also D I'm going to call it and we're going to say go to um E and then we're going to close it with a semi colon. We're going to save it And now we have d going to both of those places Again, let's just look at the code and see how straightforward it is You just call where you want it to go And you can also like, okay, let's do this again. Um, you don't have to use Characters you can do words like I want this to say, um word press And I hit save So you have you know, you can put like actual words in there So say you're creating an organizational chart or, um, you know, uh, a workflow chart you can, you know You don't have to use those characters. You can use words and that kind of stuff There is a way to embed pictures in there, but this is a beginner talk But just know that that capability is there. You can also insert images. Um in your flow charts Tables Again, like to create tables sometimes in html. It's just super confusing But you can do it in markdown. Who knew? So I have a couple of tables here. Um If we look at them, you know, you can see that there's some headings, you know, it's uh, depending on your screen Uh, the headings might like look a little bit, um Shaded in for formatting and then we have our table data. So how did I create that? We'll look at the code so You have the pipe symbol, which is underneath your delete key. Um On a american keyboard So I have everything in a pipe. So I have My i'm calling out my headings I'm saying that tables that are left aligned So I have a table that's left aligned. So how did I do that? I gave it directions I put a colon some spaces I did my pipe and then a colon and some spaces and It's on the left. So I've column one column two If we look back, we can see that all of these tables are left aligned Look at the code again To do it right aligned the difference simply is moving that colon from the left to the right Cool and then guess what when you want them centered you do the colon on both sides So we called out, you know, colons on both sides and we centered so looking again just to to Have some muscle memory. We have a table that's left aligned with the colon on the left hand side And we have a table that's right aligned With the colon on the right side and then we have center aligned with we have the colons on both sides And then also you can do it A combination of both you just have to call it So here we can see that this first column is left aligned the middle one is centered and the last one is right And then also you can leave them blank But for accessibility, that's not a good idea because as a screen reader or an assistive technology device goes through this The person may not know that this is an empty table. So you can do it, but I don't recommend it And like we can see here that I bolded the text Again, like all the combinations that we've learned before so we'll look at the source code We see that you know, this first one was uh Left aligned and then I did a center aligned where I have the colons on both sides And then the right aligned on the other one and then to have that empty table data I simply just have a space in between the pipes Um, I bolded the text remember we learned that you can do um two asterisks before and two asterisks after or two underscores after Before and after and we bolded so again looking at the rendered We have that Where all of the table data is is specific to the column left center and right And then we have bolded text within our table and then we have empty spaces again Empty spaces are simply leaving that space between the pipes And I Usually stop there because this is like, you know markdown in minutes But I have a few extra minutes at at this word camp. So I Want to show footnotes Um, there's a lot of documentation on footnotes. Um, if we go back to like the dialect thing, you know, every Flavor of markdown has a different dialect. So this one Was specific to I think like common mark So it won't always work in get hub or maybe in your text editor, but it works in get lab So I have the documentation there just so people can look at it Because it is a little bit more advanced concept and you can do footnotes in different ways. So You know, I'm if I'm writing a wiki Or read me Um, you can see here that I have the footnotes here. I have the one In the two and if I had a big block of text, this would be the first Footnote number one and this would be the second footnote number two Um, so what does that look like in code? Pretty straightforward. You know, we have that first paragraph and we wanted the footnote. So we have in brackets The up arrow with one and then when we did that second footnote We did the brackets with the up arrow two And then at the bottom we defined it the same way making sure that our Editor knows that this is number one and this is number two. So again, if we look at it we have one And two and what this does is it takes you back to the when you go scroll down This will take you back to the top of the where the footnote is um And that renders a little differently depending on on on on what flavor of markdown you use as well So just to kind of like go over things again. We'll look at that first repository that read me um, we have A title we have uh bullet points we have links And so if we look at that Rendered you can see it's like a combination of everything. Oh, I have to actually go to the read me So, oh, this is a longer read me, but this is the same thing. I have some links in there. Um I have oh inline code blocks So if we look at you know, the the code we can see that I use the hash The first one is heading one. The second one was heading two. I did my bulleted lists You should really have a space like an empty line in between those but um, I don't so uh, I would reject this as a as a commit, but um here we used our Our our link formatting where we have the link text in the brackets followed by the actual url in parentheses Down here, we have the code block where we see the inline formatting where we have the back ticks before and after And then um down here, we have another um Another uh Uh Link so again, you know, it's a combination of all the things we look at it rendered. There's our bulleted list There's our headings heading one looks different than heading two that it's you know for visual You can tell that that's the most important item on the page. That's the the page title So heading two would be you know, um following your outline, but again, we don't use them for style We use them for semantic markup. We have our nice links And then we have our nice code blocks. So we'll just kind of look at everything again just because That we can Again, we can do italics really straightforward asterisk before and after Bold is two asterisks or underscores before and after strike through is the tilde and then our block quote was that carrot in front Headings remember we can do them two different ways We can do you know with the hashtags heading one heading two heading three Each hashtag indicating another level of the heading and then if you only have two headings you can do the the title and then the the Equal sign for heading one and then the the The hyphens for heading two and then our horizontal rule was three dash lines So that's what I got for you. Um if we go back to the slide deck I don't think I have anything else in the slide deck, but let's just check real quick Nope, that's it. And I have some resources at the end for Markdown guide getting started and then I have a couple of different flavors here I've common mark, you know our common mark spec sheet Get lab flavored markdown and then also get hub flavored markdown So I'll just go back to the top and leave the url there and That way you all can see that Are there any Questions does someone want to see something demoed? And I'm relying on the chat on the side. So I'm not sure Where that would be let's go to q&a Oh, okay. So I had the wrong window open. I had the whole the whole the whole platform open I do see some questions. Um, can you create a custom ordered list? Example using an arrow instead of a circle bullet not in markdown necessarily like you can call that out and use a plugin But normally it will just format with that with that circle bullet And then there's a question that is not stupid WordPress and Drupal are different cms is very true, but you can use markdown everywhere That's what makes it portable is if you have an editor that supports markdown you can use it Not every editor supports it you have you know, I'm not sure How Gutenberg works, but I think that you can use certain styles of markdown in there Um, but again, there's a plugin that that has a markdown editor in there. Um And then Someone requested access. So I will do that Okay Um, but I don't know how to reply. Okay here hit reply And I think someone already did that but there's the link. Um for that Any questions any more questions? Oh, what's a mermaid library? So that's just a like an api that calls out like how to how to format something So we'll look at that again. Um So what was that that was? Flow charts, right? Okay, so we'll look at this um So mermaid is like Naming a specific library. So markdown has different libraries that it calls to and so it just is calling from A library that supports this kind of markdown um Not really important that you know what that means. It just means it's a It's a it's a resource that markdown pulls from and it's specific to get lab like I said So you call the library you call the graph data and then you do your flow chart. So, um, It's a like an api. I think is what it's called again beginner talk So I am not completely sure but that's a really good question Still need access for the the the the file. Okay There we go. So there's access. Sorry about that Cool Enjoy word camp. Um, thank you very much for listening and feel free to reach out to me Feel free to like play around in that get lab Repository too because it's open. So if you want to do something in there You can just edit the page and do a merge request and play around in there Um, I don't care. I'll come back and I'll like change things Feel free to like try to break things, you know, look go around and see like like what it means If you forget a space what it means if you like don't have a space, you know, because a lot of times Um, the muscle memory and markdown is coming from our mistakes, you know, we learn as we grow So mistakes happens. Um, so yeah, feel free to do that Thank you