we're here today to talk about markdown and it's a fantastic way to create documents whether that's technical documentation or user documentation whatever it may be i think it's super dynamic and great tool to have in your tool set for sure so what we'll talk about today the agenda i'll give you an introduction to markdown so i'll tell you what it is how it sort of works and some common uses for it and then we'll go over some syntax to just show you how to write markdown and i basically have that as a list of some of the most commonly used pieces of markdown but then we'll jump into when we get into examples a little later we'll jump in actually show you what it looks like when markdown is rendered i'll share with you some resources and then we'll take some questions and answers so start with an introduction right so i think the genesis of this was working with sherry and mia and ashley on some internal documentation on best practices and happened to bring up the fact that markdown would be a really good tool to use here because it's not super static like a word document would be you can change it up really easily and then you can export it to all sorts of different formats and so i think the consensus was it was a great tool and that was really where i found out that a whole lot of people didn't know about markdown so anyway markdown's a lightweight markup language that you can use to add structure and formatting elements to plain text documents so it's like html but it's specifically for documents you can apply styles to it just like you can html and have it come out different you know looking different based on the styles you apply to it but ultimately what it is is just a way to decorate your text with markup so that it renders a specific way it's not markup like you think like html where you have tags or like xml array of tags there's keys or characters that you use to say something should be an element and i'll show you that whenever we get into it so anyway with what you see is what you get editors like microsoft word you know you click buttons to apply formatting markdown it's the actual text that determines how the words and phrases should look so super dynamic easy to edit i should say why use markdown markdown is platform independent so if you have any text editor you can write markdown you can create it on any device running any operating system it is portable so files containing markdown formatted text can be opened in any text editor now a caveat to that not all text editors show you what that markdown renders to some do and i'll show you one that does but you can write markdown anywhere you can write text because all it is is a text file with a dot md or dot markdown extension if you don't like the editor you're currently using just open it in a different editor markdown is future proof so even if the application you're using stops working at some point in the future you'll still be able to reach a markdown formatted text in any text editor so if your text editor goes away doesn't matter you can use it anywhere that you're editing text okay how does it work i mean this is a very quick rundown of how it works this isn't exactly everything but hopefully at the end of this session you'll understand more how it works so markdown four-headed text is stored in a plain text file that has an md or markdown extension once a document is created a markdown tool can be used to convert the mark down to html or some other file format like pdf so it can then be displayed in its full glory i'm going to show you visual studio code and the the tools available in visual studio code but there's also some web-based markdown editors that allow you to see the results right away all right syntax so you got to kind of compare markdown with html it was built with the same idea in mind that you know html defines what something looks like markdown defines what something looks like as well so a lot of things in markdown that they'll have an equivalent element in html so just like you have h1 through h6 for your different headings in html this is how you would write your different headings in markdown so it's just hashtag space heading and you know whatever text you want for your heading i'll show you how that renders here in a few note at the bottom and you're going to see this quite a few times because the way that it's written is very important because the markdown tool that that will render the markdown is looking for very specific things so like the space here between the hashtags and the heading text is 100 required because if you put them together it's going to render it just as a hashtag heading rather than applying the styles that it should apply for each one or anything through an h6 paragraphs these are really simple they don't have any markup it's just regular text so anytime you type regular text in markdown it's going to render as a paragraph would in html line breaks can be a little tricky so you'll see this better whenever we get into the actual editor but there's two spaces after this here this is the first line and that indicates you want to move to the next line okay that's one way you could be more explicit and put an actual break an html break element in there that's the preferred way for me that's perfect way i do it because this can be a little confusing and not all text editors will show you that there's two spaces there unless you grab the line and capture the line i'll show you very clearly in the editor you know why that's important emphasis so if you want to bold some text in line with some other text it's just as easy as putting two asterisks on either side of that text that you want to bold very simple italic is even easier put one asterisk on either side and then bold and italic you would put your three asterisks on either side so very very simple stuff here and i mean see how easy it is to go in and decide you want to you know take every time you have a specific word in all of your text you want to make it bold you just search for it grab that item and then replace it with new you know new text with the two asterisks on either side and you've just bolded all of that word in your document okay so ordered lists are exactly as you would probably expect them to be where you type in a number dot space and then the actual list item unordered lists are the same use an asterisk it'll actually allow you to use an asterisk or a dash and there's some other a few other i think asterix makes the most sense because it looks like a bullet and that's how it ends up rendering in most of the markdown engines and you do have to have that space so again that note is there saying you have to have that space you can use a combination of the two as well so under the first ordered list if i wanted to you know between the one and the two if i wanted to add an unordered list item i can do that very easily just by adding a bullet and indenting the item underneath that first item all right links these are really cool because these are super easy to set up so it basically creates an anchor for you a element as you would in html and there's two things you can do here so internal to the document assuming you're using some sort of headings like we showed in the first slide the h1386 you can go to any of those headings simply so so the first part of the word or first part of the link that's going to actually show as a hyperlink text is the piece that you see here in the brackets so this link is going to say back to the top but then behind the scenes the actual hyperlink is going to a header an h1 header with docket that is named document heading with hyphens now these hyphens are added in here as part of the link but they're not in the word itself and it'll become more clear whenever i show you in the editor how that works but very easily you can you know add back to top all throughout your document and put your title header in here and you're going to have all these little buttons for back to the top throughout your document if you have a really long document external website same so the word that you want to go this is actually a phrase so use this link to go to and you can see the what i want to be the hyperlink i put in brackets and then www.google.com that is the address all right this is the coolest part of markdown and one of the reasons i think is best for documentation it's because we can do code blocks and code super easy okay so what you see in the first part here the block is three ticks tick tick tick a space js and then it's enclosed in three more ticks after code block so this prime example of this if you've been to github and you've looked at git repositories their readme files are all done in markdown so when you go in and like let's say you look at airbnb's documentation you know they have their own apis and documentation on github well they have a readme when you go to their get repository and there's tons of code in there and that read me you know tons of code examples and all of those are done as blocks here in markdom this is not something you can easily do in word or any other text editor you know traditional text editor which is why it's so useful here in markdown so i give it the language which is javascript so we can use js for short but not all languages have a short like this one does for js as you tell the language that you want to highlight the syntax and it's with the three ticks like this and then everything you put in between is going to render as code in a nice little block to indicate that it's code the inline piece is just as easy to use so if i'm writing some portion of documentation and i want the reader to know that what i have just mentioned is a function that is part of this documentation that i just put a tick on either side of that name and it will automatically make it a text that looks like code so like consoles or different markdown renderers will use different font but it all looks like code font and most of the times it'll put a little block around it too to indicate that it's actually a code block okay so onto resources and then we'll get on to the fun stuff or i can actually show you what this stuff looks like resources so where i got most of my information here because you do have to look these things up even though i've been using this for a couple years is the markdown guide this first piece so it's really great it's got all sorts of examples it's got you know explanations for everything origins of markdown links to other places all that and then john gruber's markdown documentation i mentioned that there because that's the actual creator of markdown and he has his own documentation site a little more technical i don't care for it as much as i do the markdown guide but it's there markdown tutorial walks you through step by step of creating a markdown document so that one's really great as well awesome markdown i haven't really looked at but i hear a lot about it too many things to look at here right so just another resource you could go check out and then dillinger is one of those online markdown editors it allows you to type markdown in a left pane and in the right pane you can see what the rendered markdown is going to look like so really awesome cool so that's resources now we will move on to some examples okay so i've got side by side here this was dillinger what i was just talking about i'll show you that here in a few i want to show you what we've got in visual studio code here first okay so i created with all the slides that we just went through with all the examples that i showed you i created a markdown file for each just to show you what they look like in actual markdown so for instance here's the headings piece that i showed you it's got an actual heading that says this is the headings page so that's not actually one of the headings that i wanted to list but what's cool here is with visual studio code when you have a markdown file you also get this little icon here which allows you to open up a preview off to the side of what your markdown is going to look like there we go that happened automatically okay so this is the preview this is the actual markdown now what you see over here is not how all markdown is going to look this is a specific flavor of markdown that visual studio uses for giving us an example of a rendering so it uses a specific set of css to display everything you can get all sorts of different css from online that you could apply to a markdown document or you can create your own the one that's used by get is our git is a really good one and i'll show you there's a an extension that i have here in visual studio code that allows me to export to html really easily and it applies its dial automatically so i'll show you that whenever we're at the end here i highly recommend it i'll actually go in and set the setting up to automatically generate html every time we save a document too okay so here's our headings like i said heading one two three this is how each one would render in your actual document whenever everything's said and done very useful again these the tool that i'm going to show you here in visual studio code allows you to add a table of contents automatically and that table of contents is based on these headings so you want to use these headings every chance you can because headings are like a waypoint within your document that allow you to link to them but they're also part of that table of contents okay so one through six paragraphs again super easy so we have our header here just saying what the page is and that renders as a as the header of the entire page i then have h2 paragraphs showing you that this is paragraph one this is paragraph two line break so like i told you before there's two spaces here which indicates a line break if we take this and take one of these spaces out it all runs on one line right which is why that one is difficult which is why i prefer to use the brake because you you start to you know you don't realize that the space isn't there the space that you think is there isn't there and just hitting enter doesn't do anything unless you've hit enter twice but then that puts an extra space in between that actually makes two paragraph elements is what it does rather than just putting you on a new line so since everything ultimately gets rendered through html anyway it allows you to use some limited html elements like the break element that allow you to move from line to line if you wanted to keep it all within the same paragraph emphasis oh and this one is one i didn't mention in the first document but just three little dashes like this give you a line to help separate out your content so really useful and those can actually be asterisks it can be multiple it can be more than three but it's a minimum of three i like the dashes because i like to make the left side look as readable as the right side but not as pretty right it's never gonna be as pretty but to make it as readable so that if i don't have it rendered i still know what's going on in my document all right so bold is the two asterisks so you can see it's bolded italics like we showed you before and then the bold and italic okay lists again these will render just like ordered lists or an unordered list would in html we have our h2 here for ordered list and then under list and then one two three four and to add to that so in your markdown it all automatically auto renumbers it for you if you wanted to add a fifth item but not all editors do that so if it doesn't all you have to do is you know add the number dot but there has to be that space in between the numbering and the actual item and same thing with the unordered list and so here too now it doesn't recommend that you do a mixture like this but you can do a dash and do a fifth element item and you see it treats it sort of as a well this specific renderer treats that as a separate list because it's a different item but some don't some of them treat them as the same one which is why they tell you to keep them consistent because depending on what's rendering your markdown it may display a little bit differently links okay i really love the links okay so again internal to document i've created this move to top link if we scoot down just a little bit to where we can barely see move to top and then hit move to top it brings us up to the top because i've told it links is where i want this to go which remember any header or heading h1 through h6 if you put it in the internal link like this so if this is set to links for this page rather than links you would have to make this links for this page right and now when we do it again and move to top it moves us to links for this page so you're just replacing your spaces with dashes is all you're doing for your headers so it's that easy i'll get rid of that now if i try to do it again now here with after i've changed it it's not going to move me anywhere because it can't find anything called links so again everything within this block here is a block of code i can put whatever i want in there you know multiple functions can be documented here i can give examples of how to call a function multiple times all in one block and it's super super easy to create and it automatically you know highlights it gives you syntax highlighting so it shows the comment here is green the function is blue the return is blue and again depending on your renderer those may show up a little bit different so there's definitely some renders out there that show those colors in more detail and more syntax highlighting than what you see here a string is one two so you know if i say rather than return process but i say some string you can see that gets syntax highlighted as well here and then again inline so if you're doing documentation which i'll show you in the style guide if you're doing documentation where you are you know a lot of times what you'll do is have a paragraph that describes the function that you're documenting and it will say the whatever function whatever that name is does this this and this well when you reference that function you want it to be highlighted like this the user knows or the reader knows that you're actually talking about something that's not just regular text right and it can be easily picked out and so you do that just with a tick around each one okay cool so that goes over everything like these are the basics you know this goes over the basics of markdown a document that i'm live using right now again this is a style guide and it's a definitely a work in progress i'm only using it as an example here but just to show you sort of how things work here right we have a table of contents that the tool that i have in here automatically generated for me it points to all the different headers that i have within the document so i can go to any of them if i want to go to variables i just click variables each section you go back to the top each section has a title has some sort of write-up on what's going on the item that we're looking at and then has some sort of code documentation to show you how they would do it or how you do it in the code so doing this in word i don't even want to think what it would take right because doing a block like this is creating a table and taking you know taking that table or that element whatever it may be and doing heavy formatting to it to make it what you want it to be and all that sort of happens automatically here in markdown so it's perfect for this use case for documentation arrays which you all know i love so and at the end of each of the section we have the back to the top so it scoot us right back up to the top so very useful so i used this for one of our customers who had a really really really bad code base and we wanted to show them you know how bad it was but they're not technical so we didn't want to just say oh you know yeah this code is bad this code is bad this code is bad so i put it all into a markdown document like this and i actually copied and pasted all of their script includes and business rules that were bad into the document itself so that they could see you've got like 10 pages here of a business rule that is repeating itself over and over again because somebody didn't write this code correctly and it really helped us sell the point to that customer that this isn't just a saying it's a jumble and it's a mess they can see it with their own eyes that it's a mess because the documentation was super concise and able to communicate that to them that was really useful there's one thing that i didn't show in here as well let me get it down to one page here i'm going to get it down to the paragraph page because i want to show you you can create tables really easily i want to say it's bar header 1 and then another bar header two and then is it i might have to look at the documentation on this which might be actually a good good way to do this with you guys on the phone here it is so to create a table all you have to do is the bar i didn't do the spaces i guess oh no i know what it is so if i come down here and i'll do another bar and another bar dash and another bar i can format that and it's automatically going to create a table for me and under that we just need to add the bars for data right so you know cell 1 cell 2 format and we've created a table just like that it's really cool i'm sorry yeah so three cell for i need to put a space in between these two but yeah so look how easy you can create a table too like you know in word you have to insert that and pretty static is what you can do and it's difficult to add lines and again this is just the styling of this one flavor of markup this is a different rendering in dillinger here right so where it has all of this markdown over here which is all good examples as soon as you open dillinger it comes to this by the way gives you all these examples over here and what they look like over here but it's using a completely different rendering engine here so it looks different you see things i showed you like links they're just that easy and just really readable over here and the left even though this is the raw markdown does anyone have questions not a question but i just wanted to add to your point david you know after i got with you on what you did for that one customer i actually used this type of format for a different customer for kt sessions those went really well so documenting code that we wrote for them in a way that they could understand oh nice that's great to hear i and i'm glad you said that because now you made me remember what i wanted to do i wanted to come into code i told you i'd show you what that markdown all-in-one is the the plug-in or the extension that i'm using here in visual studio code it allows you we're going to come into the um we're going to look at the preferences real quick for markdown all-in-one and i turned this off because i didn't want it to do it during the show or during the sort of show and tell but we can say print current document to html when file is saved just like that and now when we go to save it's automatically gonna pump it out to html i want to do that here with the style guide just to show you how good it looks as html okay so now we have an html there it is so style guide jshtml got saved right here we can open that up in a browser and there it is super pretty we can take this now as raw html from the actual document there and put it into a knowledge article and we have a beautifully formatted html document in our knowledge base just like that i think it's super useful i use it a lot anytime i need to document something for the customer that you know if they don't have a preference to say that they want it done in words they want it done in something else i at least pitch this to them and say hey we have this really cool thing called markdown that you can do documentation on it that's a lot more dynamic and easy to maintain and a lot of times they go for it so i think it's a a good tool to have in your back pocket for sure and i think that concludes does anyone have any more questions hey david so this sounds like a great tool so you're proposing this markdown as more of a project-based tool that developers and other people can use but are you also proposing it as a standard for all of our repository i wouldn't say a standard for all repositories i would just say for our living documents let's just say it's something that i think we should consider definitely something we should consider because in the grand scheme of things i think it's a lot easier once you've learned it and you know and the learning curve is very very small it's not big but once you've learned it it's it's much much easier to work with than a word document or something similar and you can't export your pdf as well so if you need it to be something other than html you can export to pdf and the site the top with the markdown guide it's great so here it is it goes into you know showing you dillinger and how to use dillinger it shows you what it's good for so websites documents notes books presentations email oh there's an app too okay real quick so i use this note app called bear which is for mac only and it's really great so it allows you to do markup within the actual note taking so you can see this is an h1 that automatically gets created on the creation of a note i can you know make lists just as easily as doing one dot and this is a list item you know just like that and it renders it in real time you never really see the mark down here so if i wanted to make something bold here and put the asterisks around it it will show the asterisks but it also bolds the some of them render them a little bit differently see that's bold is now one asterisk here so yeah that's the caveat let me say that this bear one uses a slightly different syntax than the actual official markdown does so but but it is a flavor of markdown that you can use in your list you can do code blocks here within this note you know taking notes like if you're i use this for everything so if i'm on the phone with a customer and i need to note something and i need to make it super important i'll bold it and do that really easily without going into crazy formatting pages so very useful tool hey david so you mentioned that you use this for your technical like documentation when you give this to the customer do you give them the md file or do you export in pdf for them i'll export it typically to html and and get them to use it so yeah so they can put in their knowledge base if they can't take it as html i'll do it as pdf pdf's a little trickier because you have elements that want to go from page to page and you know pdf tries to make you go page debate so there's a couple options and i don't have the examples here with me but one option is to make the pdf all sort of like one long document like you would see a website because there's the option to do that but the other option is you can add page breaks within your markdown so you can specifically say i want it to break at if it can break out i should say i want it to break at certain elements and so you make it break it smaller i guess smaller chunks of elements of your document and that way it'll fill in where it can and actually looks like a document at the end where it's broken down by page a little more difficult though it wants to go to html right i mean that's the path it wants to go to because i think that's the one these days it's used most often when it comes to online documentation uh so so the use cases that uh if if the customers if you're proposing okay we can do this in this format but it has to be in the knowledge article so it can't be like a word document and then if they're okay with that you would do it as format yeah and i export it as html and just a copy paste of html right into their html field for knowledge yeah it's awesome i like it i i mean i use bear to perform your recommendation i notice there's similarities like just doing both it's super quick to do it so yeah that's cool thank you yeah no problem no problem i'm glad i'm glad this is helpful well then i guess that will end the presentation i hope everyone enjoyed it if anyone has any questions please reach out everyone have a great one [Music] you