Learn Markdown in 30 minutes!

[Music] hi everyone my name is gwen and welcome to faraday academy in this video i am going to give you an in-depth look at what markdown is why and where to use it and go through everything from the basics of syntax all the way to libraries and some more advanced use cases so to start let me give you a quick 60 second overview of what markdown is markdown is basically a simplified markup language that is used for formatting text it gives you a way to write your text so that it can be compiled to html

now markdown has been around since about 2004 this is actually the original announcement blog post where john gruber introduced the markdown language which like he says was a text to html formatting tool that he called markdown so why would you use markdown markdown is actually much easier to learn use and read than standard html and it's evolved immensely in many different ways over the last 17 years so now it's one of the most popular ways to format texts for blog posts documentation even in things like note taking apps of course python notebooks people also do

some super cool things with markdown like creating tables and flow charts and even writing whole research papers and books in this markdown syntax now basically i was researching why there are several different flavors of markdown and sometimes when you use it in different places you'll notice a few minor differences this is apparently because the original specification left many questions to be answered so people basically came up with ways to fill in the gaps on their own so when you look at sites like github that supports markdown and even has the default standard readme.md in other

words markdown files they call it github flavored markdown meaning it's markdown plus a few additional features that github gives you access to if you use markdown files on their platform let me quickly list off some of the most popular apps that support writing with markdown for note-taking you have bear standard notes joplin and my current favorite obsidian that support and use markdown by default for blogs what i use for my own blog and free codecamp also uses for their blog is a platform called ghost that also gives you an admin interface where you write the

posts in markdown as well now when you go on forums or other blog sites then you will notice that you can probably use markdown to format your text there as well for example discourse forums like the free code camp forum and many other development forums support markdown it's also very popular in the jam stack world where you can write any type of content from blogs to articles to just basic web pages in markdown and the plugins automatically handle converting it to html and rendering it on the page as i mentioned before if you use python

notebooks which are pretty standard in a lot of colleges and coding programs now you can use markdown in any of those cells to write notes format text put headers anything else so let's dive into some of the basics now i'm going to be working in this repository that i created in the past it's basically a wiki for django projects and all it is right now is just one readme file which you can see from the extension is dot md so it's a markdown file and you can see it's nicely formatted text with headers some regular

paragraph text bold text here's a list of links to different sections in this same article here's an unordered list with an external link to this library and there's also some code blocks here you can see they are properly highlighted and formatted some nested lists more headers and subheaders and you get the idea so i have cloned this project locally already and you can see that it looks much different in the actual raw code file over here you can see there was a big header which django setup wiki this is just a paragraph bold and a

list and you can kind of get an idea of how it's formatted over here now i'm going to create a new file and start from scratch to show just some of these basic features of markdown first so i want to add a section here and i want to talk about how to set up graphql projects in django so i'll call it graphql.md and now that i've created this file i can write any type of markdown in here and any code editor like vs code what i'm currently using will recognize this as markdown text so let

me write my first line of markdown and then we can preview it so i'm going to put one hashtag here and say django graphql and i'll save that now vs code actually lets me take a look at this in preview mode if i right click and say open preview so i'm going to click on open preview and now you can see this is how it would actually display the text if i was writing it in a markdown supported environment like github basically if i put a hashtag in a space this renders to an h1 in

html if i put two hashtags this is an h2 you can see it got smaller three hashtags is in h3 4 h4 and so on you can see in the browser i'm at the top here of the previous page i showed you so the readme if i right click and inspect element i can see an h1 is rendered here which in the readme corresponds to this line of text at the top which starts with a hashtag now it does have to be hashtag and then a space or else it's not going to register as a

heading so you can see now it's just plain text now a line of plain text does automatically render as its own paragraph so if you look back in the readme file there's instructions for setting up django projects if you see in my html that is a paragraph tag even though there are no special symbols or elements or anything around this now let's look at different styles let me add another row of text here first let me fix this header and i'll say instructions for setting up graphql in a django project now i'm going to make

another table of contents and i want this text to be bold so i'm going to use two stars or the asterisk symbol and say table of contents and you can see when i add the closing to asterix my syntax highlighting came on so if i save this and preview it you can see that the table of contents is bold text and this is just regular text now along the same lines if this was just one asterisk see now it turns purple and this displays as italic text if i wanted to strike through an element then

i can add two tilde symbols to the beginning and end of whatever text that i want to strike through and you can see there is a line through this text here that's really useful for lists and also for editing contents now these things don't have to be used in isolation so for example if i had bold text i could also have italic text in the middle and you can see it's bold and italic now for the table of contents just like i have on this page here i'm going to create an ordered list now for

an ordered list or a numbered list i can just type in the number followed by a period and then when i hit the space bar you can see the color change slightly on the one so you can see markdown is now recognizing this as a list let me just add a few elements here and you can see this is a pretty normal looking list now there will be some formatting such as indentation added depending on what application you are writing your markdown in you can also nest these list items so if i wanted to nest

an item let's say inside of graphene and go to my preview you can see that it is nicely indented inside of the parent list item i'm going to get rid of that line now one thing that often happens when you are creating long lists of things is that you inevitably have to switch around items let's say i wanted to move item number two to before item one so i just copy pasted it but now i have to update this number and then i have to update all following numbers as well so that they are correctly

numbered and now if i want to move that back which i do now i have to do the same thing again now one way that most platforms support that allows you to avoid this is by using the number one for every element in the list so i would just say one one one and then mark down basically handles numbering them based on their order so we can see this in the preview it still says one two three and everything is in the correct order even though we're just using one one one that is a really

handy kind of extra feature of markdown that is pretty widely supported now let me make a section for the first item here i'm going to make a sub header so in h2 and inside of here i'm going to add a code block now i could do this two ways i can use an inline code block or a multi-line code block and i'll show both of them so line i could say install graphene one more l and i can use a back tick here and then i can say something like pip install django graphing and then

close it with a back tick and you can see my highlighting change there and if i go to my preview you can see that it stands out as formatted text now if i want to do a multi-line code block let me just add another header here so creating schemas i can use three backticks and then paste my code in here and then close it with another three back ticks at the end now if i go to preview here you can see this definitely stands out as a code block keeps all its formatting and it does

look pretty nice however there's one more thing that i can do here and that is actually tell mark down which language of code i am putting inside this code block so i can use a shortcut here like js or python py for python which this code is python so i'm going to leave that now if i go to my preview you can see it's even properly highlighted now and most interfaces will let you highlight your code blocks as well by defining what language you're putting in the code block now let's say i want to add

a separator somewhere in here let's say right here after instructions and before the table of contents i want to have some kind of horizontal line so here i can just add three dashes let's go to my preview and you can see this whole gray horizontal line above the table of contents here that is from the three dashes now you might notice there is this other thinner line up here and many platforms underneath an h1 tag so main header will add some kind of thin horizontal line for you just to provide some natural separation for the

text but you can also add yours manually as i just showed you here now let's look at some block quotes here let me actually add a horizontal row here and now let's look at block quotes this is also very easy to do you basically use a right angle bracket followed by a space and it's a block quote so if i wanted to quote bob ross for example i just pasted in a bob ross quote now if i go to preview you can see it has a special quote syntax now if i want to also include

the name of the person who said this there doesn't seem to be an official standard way to do that so a lot of people will just use something like a citation tag by the way because two lines in a row i'm 55 and 56 have the right angle bracket these are considered to be in the same block quote because they aren't separated by empty lines so here i'm just gonna put a dash and then i will include a little bit of html a site tag and then i can say bob ross so i am going

to use a double dash and it shows that it's by bob ross i could put another blank line to separate these two so now you can see bob ross it put it on the next line now some people say that you should have the name outside of the block quote so do something like this and i could even make this italic and preview it and i could do something like this now just like mixing bold and italic and those sorts of things you can also nest anything inside of a block quote so you can have

bold text you can have lists links anything you can even nest block quotes inside of block quotes so let me do that real quick i'm going to use another bob ross quote and i needed to have one line separating the attribution so let me add that in so it doesn't think it's being part of the block quote here now if i separate that you can see i have this main block quote and then i also have a nested block quote that's indented this is a really useful feature for forums and for places like the github

issues section where you're quoting multiple people now speaking of different types of lists i'm going to add another section here with an unordered list let me scroll up and right under here i'm going to add another subheading and just add y graphql now here there's no particular order to the reasons why someone might use graphql so i'm going to make it an unordered list now there are several different ways of writing unordered lists you can use an asterisk but i recommend using a dash which is more widely supported and places like obsidian which is my

current note-taking app if i use an asterisk it thinks i want to make italic or bold text and it's a little bit of a pain so it's just easier to use one dash here even though some platforms like github will support using asterisks for list so i could say something like get only the data that you want easier to manage endpoints let's see how this looks and here you can see the unordered list pretty much the exact same thing as the ordered list and let me add this to the beginning of my table of contents

see how easy it is using ones here i just add it to the beginning and my list is correct now in my readme over here all of these items in my table of contents are links you can see here like if i click on this link it takes me to this section of the project now this is something that a lot of platforms support and that is automatically generating ids for all headers in your whole document based off of the text in the header so if i right click off of this header and usually it

does this for h1 and h2 headers you can see the h2 here and there's actually this nested element which might be hard to see but it's this little link tag that shows up to the left of the header when you hover over it and basically you can see this is a custom generated id user hyphen content hyphen general hyphen setup and so on of the whole header github and many other platforms do this automatically for you so what this means is so if i have an h2 tag like graphene installation i can create a link

here with the link text the text that's going to show up on the screen inside of square brackets and then right next to that i'm going to put parentheses and inside of the parentheses i'm going to say that this links to an id so i'll start it with a hashtag and i'm going to say graphene dash installation it's all converted to lowercase so basically it's this exact same thing as the title here but converted to lowercase and any spaces are hyphens so let me preview that and i can see now this is a link and

if i click on it it takes me to the graphene installation section and i can do that for all the rest of the sections here so y graphql i can wrap that in square brackets and put parentheses and here there's punctuation there's a question mark in the title but i'm just going to leave that off so i'll do y dash graphql and then i can go to my preview y graphql and it takes me to y graphql so in general you want to leave punctuation any type of punctuation you have in a title here that

won't be included when the id is generated but if you ever have a question on the exact id that's being generated again you can just right click on one of these titles so inspect and then i can see whatever id is being generated here so what if we want external links not just internal to different areas of our document we can basically do the same thing let me add a paragraph up here i'm going to get rid of this horizontal row and let me just add square braces and i'll put some linked text inside let's

say we want to link to the graphene documentation which is the django graphql library and i have the link already copied here so i'm just going to paste it so now basically if i go to my preview document i can see here's a link graphene documentation if i click on it vs code is asking me if i want to go to this external website i'm going to say go ahead and open and it takes me to the documentation here so what about images i just went and pasted this image this image here manage poll this

is just a mock-up from an application that i'm building on my live streams but i basically want to try to embed that inside of my markdown file here so let me come to the bottom here and this basically uses the same syntax as creating a link except you start with a bang or the exclamation point there i'll just give it some text in here i'll call it pull mock-up now the text inside of the square brackets for an image that's going to be your alt text for that image and now inside parentheses are the path

to that image so i'm going to say this is actually kind of a strange image name because there are spaces in it so i'm just quickly put in underscore and say pull page let me come back here and i'm gonna say poll underscore page.png i need to add the dot there so it's in the same directory and now my image shows up here now what if i want to create a link on this image in other words turn the whole image into the link itself i can do that actually by wrapping the whole image inside

of another set of square brackets just like i would any other piece of text and you'll notice this across all of markdown that you can nest and kind of mix and match wherever you want so i'm just going to grab the same link that i used earlier for the graphene documentation and paste it in there now if i go to my preview you can see i have a different cursor over the image and now if i click on it it comes up with this same do you want to go to an external link dialog box

i'm just going to hit cancel now there are a few other things and one thing you will find is that generally in markdown you can use html tags as well so if i had some text here and i wanted to put it on multiple lines for example a common thing would be to use a br or a line break tag and then i could put some more text and then if i go to preview i can see it is on two lines i could do this with anything i could use html image tags paragraph tags

any kind of html tag i could put inside of my markdown sometimes for more advanced features you might want to embed html tags inside of markdown a lot of platforms do support this some might not but it might be a good option for you now one more thing that i do a lot at the bottom of my readmes and is just something common you might use in markdown in general is to create task lists so let's say i had something like a road map here i'll put that as an h2 tag and then here i

can actually create a list of tasks that i can check off and what i do is i start it by using a dash space just like i would any other list but then i have square brackets and i put a space in the middle of them and i can say task 1 and then task to etc and if i look at the preview so it seems like actually vs code doesn't support this but the basic syntax would be if an item is checked off you would put an x in the middle otherwise you would leave

a space in the middle here you can see that it works but it's definitely not formatted so let's take a look at this task list in another interface and you can see i pushed my markdown file up to github i'm going to click on it and if i scroll to the bottom i can see these actually render as actual check boxes so in most interfaces such as my note taking applications and github flavored markdown these types of check boxes the square brackets with or without an x in the middle they will render as checked or

unchecked checkboxes those are all the features for the very basics of markdown now let's look at some more intermediate features let's talk about tables next i'm going to come to the end of my graphql.md file and just get rid of all this extra temporary content now tables can get pretty complex so i'm just going to show you how to create a simple table because this is generally what you will need let's say we want to make a state diagram or i guess a state table i'm going to put name here and then i'll just give

it another space and another pipe symbol and then i'm going to say current state and next state these terms don't mean anything for markdown of course this is just an example that's on the top of my head right now so i decided to use it on the next row this is where my dividers are going to be and a divider is basically a bunch of dashes optionally prepended or appended with a colon and what the colon means is that is where the text will align so if you have a colon at the beginning to the

left of the dashes here that means your text will be left aligned to the right that means your text will be right aligned and if it's on both ends then it will center your text inside of the cells so i'm gonna keep it left aligned usually i'll put a standard number of dashes here put six and six space and then a pipe and then and then let me go ahead and create a cell here i'm going to say green let's say light color let's say this is a stop light so light color if the light

is green then the current state will be green and the future state will be yellow let me save that if i go to preview you can see i kind of have a table here now tables will look different on every interface so if you're displaying a table on github versus a python notebook versus here nvs code the table is always going to look a little bit different but it's pretty much the same idea with column headers and then content for each cell so here i could also do a second one here so if i do

yellow i'll just leave it like this so i'll do yellow and then red and you can see i don't need to explicitly put extra dividers between every column it will automatically give dividers usually there are vertical dividers as well but i guess in vs code they're just implied here because it creates a space separation between the next column one of the coolest things that i have found in markdown is actually being able to collapse and hide text using a collapsible element now this is another case where you use html in the markdown so i can

actually use something called details and inside of this details tag i'm going to also use a summary tag and inside the summary this is going to be something like a section header and then inside details i'm going to put some more text that will be hidden or optionally hidden i'm going to say section body text and now i'll close the details tag let's take a look at this over in our preview so here you can see all we see is the section header text but you can see i clicked on it and now the section

body text displays i can fold it and i can show it so basically the only text that's shown is section header whatever's inside of the summary tag and then you can put as many things as you want inside of the details tag anything outside of the summary tag though will be optionally hidden and you can have lots of other stuff here like i could have a list and all of this text would be hidden inside of here yeah so if i don't indent the list it actually displays properly in markdown one other interesting element that

can be useful is footnotes i'm just going to create a header here to create some kind of separation and here i can just type out a sentence and create a footnote by using square brackets and then i basically need to use a carrot inside and then whatever text or number i want to reference that footnote i think it's usually a number but you can also put something like text here i'm just going to use a number and then let me make another header let's say i have some kind of footer at the bottom of the

page and then i basically make an exact replica of what i used for my footnote here so i'll use square brackets carrot and one and now this should automatically link now again this is one of those features that isn't in the default markdown syntax so it might not work on every platform such as vs code it doesn't recognize this syntax it's what's called extended syntax now i pushed this to github as well and if i scroll down you can see that actually github doesn't support the footnotes feature either but this is supported in many note-taking

programs so it's something good to know about for example it works really well in obsidian which i use for all my notes and many other things those are all the features that i am going to demo for markdown now i do want to go over some of the other cool things that you can do with markdown for example markdown has emoji support so you can paste emojis inside of your markdown files it also supports typesetting with latex if you want to embed formulas and things like that inside of your markdown files if you don't know

latex is another text coding language where you're basically creating research papers and pdfs there are also a plethora of plugins in the markdown ecosystem for example mermaid js which is basically markdown inspired text definitions and you can create these in programs like obsidian and then directly from your markdown files you will be able to see flow charts and things like this if you want to know more information about mermaid actually learned mermaid from one of my friends a fellow youtuber brian jenks so i'm gonna link that video for you to go watch if you want

now there are other markup languages like python uses rst which is restructured text and you see a lot of python projects use rst files which is pretty similar to markdown but mostly used in the python community and sometimes documentation can be auto-generated into those files there's also mediawiki basically wikipedia made its own markup language i think they created around 2003 for use on their platform so they also have something similar to markdown but not exactly the same but if you learn markdown the concepts will be similar to many other types of markup one other really

cool use case for markdown is actually writing books and i found quite a few examples of this online there are actually people who write and format entire books by just using markdown and i almost wish i had known about that before i first started writing my book in another editor and this is even popular enough that there are tools created for people writing their books in markdown that's it for this video i am going to finish updating my documentation here so feel free to take a look at this repository i'll link it in the description

below let me know if you have any comments suggestions or feedback i really encourage you to spend at least an hour or so trying to learn markdown it's pretty simple to pick up and it's just used in so many different places now that anything you learn will definitely not go unused thanks again for watching and i'll see you in the next video