Jammin' with Markdown — David Wells

yay alright as mentioned I'm David wells work at serverless if you haven't heard of it and you're building static sites and you need some sort of function to run to do something that you can't do on the client check it out titled my talk was advanced markdown but then I was like that's kind of boring so I was like what's that with markdown and I was like wow that's kind of cheesy I was like markup with markdown and I was like no that's still not right and then I kind of settled on this one feel the rhythm feel the rhyme get on up it's markdown time so let's do it that's all my slides because this is about markdown so this talk is written in markdown and the slides can be found here if you want to check them out we got a table of contents that's fancy oh yeah all right cool so this is basically kind of what we're going to talk about why markdown everyone here probably knows that I'm gonna go real real real fast because I have a lot of different resources and kind of tools that I want to show you guys and kind of how we use markdown at serverless to build out our entire site all of our Docs pretty much everything even internal company repos am I going to show that but we do it alright cool so yeah so why markdown I'm gonna zoom in I've never I've never done slides in a markdown file before so you might see the head so anyways alright so why markdown 1 because it's open like we put it on github anybody can fix typos update any of the content as mentioned in the previous talk you have a running history of everything every change that's happening it just makes sense and if you ever had to like revert something in WordPress and like go grab a sequel like snapshot from a day ago and try to figure out like run that locally and it's a huge disaster so everything under version control makes 100% sense and then the other reason why we use markdown for everything is like mentioned in previous talk no CMS kind of lock in markdown is extremely extremely portable we can use it with any static site generator and it's kind of the the language of choice for documentation and pretty much everything on github and it's just simple there's really no accounts to manage except maybe a github account and no CMS that we need to deal with no plugins to install or upgrade and make sure everything's secure we run a static site so everything is by default basically secure there's some markdown basics everyone here probably knows all that stuff if you just google how did you markdown there's two links here the github Doc's and then a daring fireball that's like the one that always shows up about how to do basic basic markdown stuff I wanted to jump into some more advanced formatting tips things that we like to do to make our readme Xand Doc's on github just more pleasant visually pleasant so real quick so left image alignment how many times says like have you put an image on github but just centered or huge or it just looks like crap this little snippet here float something to the left or float something to the right or Center an image and if you're not familiar with Phil Marie use it for everything for every project the clients will love you forever so those are like really basic things but you can basically you know if you are using animated gifs for demos and stuff like that it can go a long way and if you're familiar with the service project and you've ever seen any of our readme it's like our CEO is like freaking crazy about gifts he used to he used to make videos in Hollywood and he just makes gifts for everything it's a little overboard in my opinion but gifts can you know a picture speaks a thousand words a gift speaks however many frames you know times that math etc cool so use some of those we also like our blog is hosted on github as well this is actually I just stole directly from our blog guide where we keep all of our contents because some people aren't really familiar with work down yeah so there's some more formatting tips over there how do so how do we get this guy how do we get this expand and collapse that's pretty cool all too often you see a project and it's just full of just a ton of stuff it's a humongous wall of text that is you just don't want to consume because too long didn't read basically so how do we get this guy in github with a very simple collapse so just put everything in a details block give it a summary of what you actually want this show to expand and you can put stuff in hidden block super super simple this is like I can tell my Aaron's face is blurring but yeah so just use this it's it'll go a long way with ya basically not overloading people with stuff and then some other quick things so on all of our read means we always put like our links and stuff at the top of our readme so this is kind of a marketing thing but if you do want traffic back into your site or your project which you probably do toss those up at the top and do that very important badges oh my god badges man I'm gonna change the name of this talk to badges facepalm all right so badges I don't write under like badges you can use badges I know they they do serve a purpose to show that your projects updated there are some really cool use cases of badges too but I'm just not a fan you can use badges that I just want to throw that in here as a you know joke if you will so those are kind of some of basically if you were reading any of those like about markdown they don't tell you about any of these these are just things that I found in the wild of formatting tips that just make markdown files just more appealing in github specifically and then some useful markdown packages so as mentioned in the previous talk and if you do have a site running you know with markdown you typically have your metadata in a camel frontmatter so this package gray matter it's parently faster than all the other frontmatter parsers this is extremely extremely useful for like writing custom scripts with so we actually use this in our build process which I'll show in a little bit but basically you can update or change any of the frontmatter very easily it turns it into a JavaScript object that you can just manipulate something with so I actually took I use this package as well to port my old WordPress site into just markdown files using the WordPress JSON API pulled it down grabbed the post meta turned it into frontmatter so it's like ready for my new static site which I haven't got around to launching yet one day remark so most well I don't know if it's a most but a lot of static site generators these days use a project called remark it's a pluggable tool that you can basically like extend different pieces of markdown you a lot of projects use it to render markdown into HTML or into react as gatsby using remark yeah so gatsby uses remark we use Phenom ik I want to talk to you after about some of the differences but yeah so remark interesting tool am I going too fast is everyone following I got a lot more okay cool so another tool and this is a shameless plug but I made a project called markdown magic let's take a look but basically one of the the biggest problems with markdown or documentation in general is like it gets old fast it gets out of date code changes gets out of sync you gotta go remember to manually update these Doc's it's a huge huge pain in the ass in the butt okay this is PG I forgot okay so markdown magic what it is is a project that will basically keep your markdown files up to date via from source code or from external sources or from wherever you want it's basically a way to sing stuff back and as I mentioned before yes use gifts basically the way that it works it's just an impact balajl talk about that in a second you can run you can run it from a custom script a script or you can run it via the CLI for your project which I'll show in a second and basically what it does is it will take a markdown file let's go to the presentation here and zoom so what I could do and let me actually I'll open the project in a second as well to show a different example but what it looks for markdown magic basically looks for a code block like this so very similar to always mention in last talk like a short code you can basically wrap text in basically this is what it looks like you can you can change this word to whatever you want I just put auto-generated content so when people are looking at the markdown and they know don't mess with the stuff inside you can even put like the read like stop sign emoji in front of it and what-have-you but basically there's a start and a stop block and then you give it a command out of the box there's a couple of built-in transforms so there's a remote transform that will go grab a remote and insert it into that block or you can give it the code command and give it the path to whatever file and it will pull in that source code and stick it right in there and do all the syntax highlighting stuff for you and then there's also this one is a table of contents so the table of contents that we're viewing in this presentation here this was automatically generated how many times have you made a table of contents and a markdown file and you're like that's not a date I gotta go update that thing that's a machine job not a human's job so basically if I get rid of this guy they whatever let me see am i in here yeah cool so inside of this package here I'm just using it from the command line or maybe it's yeah I'm using it from the command line NPM so I'm just doing MPM run Docs it will type through and and this looks for a glob pattern too so you can run it through an entire directory of markdown files you don't have to give it each individual file for you it's using gulabi under the hood highly recommend that if you're doing any file system stuff basically if we go back and look at the there we go I guess I should have shown you that and like went right back but I swear it just did that okay and if I were to change any of these headers in this file it would basically update the text and then with these transforms that are built in there are some options so like I could have a table of contents that's not collapsed I just in my options here I'm passing it collapse equals true and then like the text on the like expandable thing says click here to expand so you can basically build things with options for to make them more flexible yeah so as I mentioned this is like completely pluggable there's a couple of community members community like three people we're grown big man you're going yeah so there's a couple of examples out there in the wild of like basically this is a plug-in that will automatically insert a directory tree of your project like how many times have you manually done that I've done it once and I was like I'm I can't do it it's stupid so that yeah so github contributors so this was a cool idea I got from Kent C Dodds he has an all contributors CLI project or project yeah we're basically you can put in who's a contributor your project it'll generate a grid of your contributors and like kind of give them props right and you read me super cool so someone made one for that a word count and you read me this wouldn't necessarily make sense if you're just showing this on github but if you were using this markdown on your sites you could put that into your build process put a word count right into your markdown pool so yeah how do those work how did the custom transforms work let's actually go look at a quick demo so here I have a demo MD file I'm using just the custom script to demonstrate how this works markdown magic if you're using it like as a script like including it as a package you just give it a path again this could be a glob path you give it a config the config can have custom transforms so this is actually how the plug-in system works where when it matches whatever your custom transform name is it will take that content do whatever you want to it and then spit it back out and it and update that block so in this example it's basically gonna like change this dummy text so let me just run npm run demo and then if i go back in here yeah so here is the replace text and you can see like I passed it an option so it says dude I believe that so it's working yeah so options option one is dude so that's basically how the plugins work so you could imagine and this this example we're actually using I use this on the markdown magic Docs all all of the documentation for the mark that magic project because why not dog food your own tool is generated from the source code so all the transformed documentation is like directly where that code lives so if I ever change it I know like make sure you change that comment block to keep the docs up-to-date instead of going finding where that doc is blah blah blah so what this does it uses a package called Docs which is super handy from TJ Holloway Chuck I don't know if I'm pronouncing that right or basically it will parse your any given code file for Jess Docs and spit that back out and then I'm just for my really simple use case I'm just putting it out as a string but you can use literally any rendering engine you want to render that back handlebars you could render this back into your markdown with react if you wanted go nuts it's completely extendable but yeah and then here are just two plug-in examples so in my transform block I'm just including a like a local one and then if I actually wanted to use one from NPM I could just like import the count one and then if anywhere in my markdown the transform count it would count the words in my document and spit it back out in that block so that that's markdown magic in a nutshell it's because like I we have like a million different github repositories and keeping everything up to date is rather tedious so I needed a programmatic way to do that so this actually helps us with like our build process basically yeah so that is the demo let me show you guys go back to my slides yeah okay cool and then let me show you one more example weird move on so with serverless we have a ton of examples of like things that you can build with server lists it's like API endpoints custom cron jobs bah-bah you don't yeah I'm not going I'm not going into the spiel but I check out his repo if you're interested in what like you can do with serverless but in our readme we have so many examples we also have so many examples from the community of people building projects with server list service has more than three contributors so but so basically these Doc's are generated from just a JSON file in this repository so community examples because we want this data not only like in our readme but we also want to consume this let's say on our site to show community examples or type this in now Golia or whatever so we wanted it and kind of like a consumable data format ok JSON and then basically we just have a regenerate readme JS file that pulls it in there's a couple of just helper functions and it just generates a table and it's just spitting out like the actual markdown for the table if you ever had to like make a table and markdown freaking nightmare so yeah so basically maintaining this table like while not impossible very unpleasant so yeah so basically and and this is actually another styling tip you can put break tags in a table to make it multi-line so nice and pretty and then the other thing I'm doing here is I'm actually grabbing what let's see oh that's not the I'm grabbing what the actual extension of the code and giving it the actual syntax so that's yeah same with here and we use this on our main readme we use this on a lot of different read Me's to generate stuff so that's markdown magic in a nutshell hopefully you can use it and enjoy it and contribute back to the community all right cool yeah so okay so that was some of the kind of useful packages I wanted to mention there's a couple of different useful utilities as well because I work I work in markdown way too much and feel its limitations you know frequently and that's why great CMS's are being built but one of the problems with our blog for example so we have you know someone managing our content one of the they they wanted a way to schedule blog posts which is like just out of the box with WordPress but then you you're in WordPress so I had to solve this solution or solve that problem rather so this is actually no one's seen this but you guys this is like a sneak preview we're releasing this next week well basically this is a post scheduler for static site generators so check out Hugo Gatsby Phenom akiti cetera whatever what it is is a really bare-bones serverless project and what it does is it basically let me actually show you guys some of my tests commits so inside of here this is our blog so it like typically when a new blog is submitted to our site it's in a new branch from an author it could be internal or external then we review that post and then what used to happen is someone had to be there at the time to publish it to basically trigger the net Liffe I build and this is not in our main site I'll get to that in a second but basically we needed a way to schedule it so the way to schedule it is just by if you're a collaborator on the project it basically checks of your collaborator and you have like basically merge rights then it will a cron job is running every hour or every what however often you want to publish you could set it every day if you wanted if you don't want to run the lambda too much this falls well under the free tier of AWS is like lambda though and it just runs a cron job every hour to check if a scheduled post is ready to go and if it is it will then publish that but once you schedule it it basically calls back already the post is scheduled and then once it actually publishes it publishes merges it and then it automatically merges it into your master we have it set up here so that trigger is an elf I build and we'll rebuild it and publish the blog post for us so just real quick I'll show you what that looks like again this is like you can use this with any project totally for free but we have to it listens to github web hooks so you just plug in your github webhook URL and then let me actually show you that inside of live there's a couple different files here so a web hook listener so this is like a lambda function that basically like is listening for events when a new pull request is submitted it hits this lambda this lambda goes makes verifies first that it's from your repo just so nobody messes with you that's highly unlikely that that would happen but you know safety first it then validates the user then it grabs the actual pull request data to save it the SHA because that's what it needs to merge will save the unix time then it'll basically save it into dynamo DB and then post the comment back to github so that's the first step this will just run for you if you just plug in your configuration options you just got to give it your github repository and your github webhook secret generated an API token so you can get that data and have rights to merge something back in and your github username also for requests so that's the first part and then the second part is just the the publish the scheduled post which is super simple it just does a DynamoDB scan give me all the items if any items like basically match if the post time is less than now okay it's time to schedule this then we go ahead and merge that post delete it from the database and then post the comment that hey we did it so this is running like totally inertly in our AWS account I guess 24 times a day you get a million free invocations a month with lambda though so that's pretty handy and yeah so that's like an example of a really simple service service that you can use to like extend your site and then the act the way this is actually config is with the service that llamó file I'm not going to go into it but really all you need to do is is configure your secrets and do a server list deploy for your repository so hopefully you guys find this useful did you guys see a mess schedule stuff alright okay yeah yeah yeah not right now but that would be that would be pretty easy right so the same way that we're list I'm listening I'm just listening for a specific pattern let's see inside of the web what's that yeah yeah so that that could do it or so I'm just matching this pattern just to the schedule pattern with the blocks I could say like cancel or whatever or yeah same way and then just run the delete from the database or whatever yeah cool so that's the schedule post tool that guys can't use yet but next week ping me about it yeah so that's one of them okay so this other one I actually found from the Gatsby project I was like what that's amazing and it was the zero friction inline editing where basically this was it's a project called wiki hub where basically you don't need admin rights to submit a pull request to update content so like basically I could come in here suggest changes and say like lol describe my change I submit that through and then through its magic it basically just submitted an anonymous pull request for me so I don't even need a github account to submit content I can like oh there's a type of there I'm just going to update that real quick inline super crazy awesome and something that I'm looking into to adding to our site as we speak probably cool cool so yeah and then just some of my favorite editors I use by word so I wrote this post in by word it's just like a crazy minimalistic markdown editor it gets out of your way I like the iOS app even better because like the keyboard it just gives you like the pound signs just right there so you don't have to like yeah yeah you know what I'm talking about I use a lot of noises and they're my presentations and then type aura is somewhere team members use that I haven't really gotten too much into that and then this is really cool how many times have you seen like a really sweet chart or drawing that someone did in like ASCII and you're like oh my god this person has way too much time on their hands the way that they're doing it there's probably a lot of tools out there like that there an online editor that I found but it was not as good as mono draw so mono draw is super crazy awesome it's basically Photoshop for like ASCII tax so if you want if you're trying to explain a complex flow in a github like issue or if you wanted to put that into your readme you could do it really easily like basically with this tool like crazy awesome so this is actually our like off blow for our static site that I'm working on but uh yeah so if you're looking to make really this cost like 20 bucks I think but totally worth it very very handy and then my favorite way to make gifts is with cap so cap is also free I think it's an electron app I'm not sure about that but basically if you wanted to capture a portion of your screen make an animated gif super quick toss it into a readme yeah you can do it that way once quick aside one of the some people on my team didn't know that you could do this but if you just want an image real real real quick you don't have to actually create an issue and github to upload it to the CDN you can just let me see that's a secret ok so if you just create a new issue so I'm using I use Snagit to make screenshots really quickly how they recommend it but I can just like literally copy and paste that and now I can just drop this into my markdown file and then I don't need to create this issue like github CDN thank you for the free files yeah so as a quick aside that's how you can also put images in markdown really quickly cool and then if you're not using this I use I use Adams sometimes as well to edit markdown as pretty good syntax highlighting so I can just kind of scan real quickly there are some packages as well to do github style previews so you don't have to like go and test it in hub and all these are live links in this presentation by the way um so you can check those out and then just to show you guys how long I've been human markdown I made this tool my site is actually still on WordPress I'm I know alright I'll leave I'm sorry I'm so sorry guys I let our everyone down I'll pour it over soon anyway so if you are still stuck or a client or for whatever reason they have to use WordPress I wrote this plug-in a while back that supports github flavored markdown and syntax highlighting for like code kind of driven posts so check that out if you do need to deal with that and hopefully not oh cool alright so those are a lot of the tools how much time do we have three minutes oh boy oh boy okay so how we use markdown so we have three separate repositories so our site like I mentioned we're using phenom ik to run our site if you're not familiar with react driven site generators super awesome the reason why I'd recommend it the build time isn't as fast as something like Hugo but if you are using a react driven site generator like Gatsby or Phenom ik you get this like single page application look and feel that's like crazy crazy crazy fast to navigate around and then this is also offline so like immediately you know when you visit site serviceworker boots up downloads everything if you lose connection or if you're on a plane or whatever everyone can see everything on your site still which is a ux win in my opinion anyways yeah so we use phenom ik to do the build all of our blog content is inside of the blog repo this was too one so it's easier to find stuff in our blog because otherwise it'd be kind of nested inside of a couple subfolders so it'd be harder to find for contributors and to because we didn't want to tie it directly to the site build this is like completely agnostic markdown that can run anywhere and we actually use the convention of kind of how Jekyll does it this is also a tip if you don't do this and you're not using this date convention looking at this in a Finder window or whatever is it's insane and you can't find anything you're looking for which is maybe you can if you're like a finder ninja but that a job title okay the other yeah so the other reason is yeah we also wanted our docks of serverless to live directly in the repository because if you're looking at a project you want to see the docks directly like where you would expect them so that's inside of our github repository when the site builds phenomena kicks off kicks off the pre build script it pulls in it downloads this repository and it downloads the blog repository takes all those markdown files puts them into our content folder runs the phenomics build process and then our site is built sounds crazy and it kind of it mean it's it's more steps than it needs to be because we've split it out in the three repos you don't have to do that but there are some benefits do that again your Doc's living close to the source code and you know other things the way some other quick tips here is so in our Doc's we link back to the main Doc's site on every single markdown this is also like a script that I wrote that basically says okay you can read it here and I like on github if you want but read it on our site you'll navigate faster there's built in I'll go search like better experience over there also you know we can get you to become a user etc oh yeah the other the other thing that I've strongly been consider is how many times have you been to github repository and been like traversing around their docks and you click on a link and you get the the Jedi who knows the Jedi he knows a Jedi the 404 you get a 404 on almost every single readme historically through every single repository the problem with that is is because like someone forgot to update a relative link somewhere and it's pointing to something or it just doesn't exist anymore so you have no power over that anymore whereas if you link every single because these like are parodied on our site if we linked to to those we have thanks to the power of metal Phi and their redirects we have the ability to redirect that 404 to any to the new docks basically you can't do that with github and you're just getting you I wish they gave you these stats on how many 404 is you get it's it's insane because so many blog post about things linked to directly to markdown files that are for force and it's a crying shame anyway is a lot yeah so just some one more quick tip I would recommend doing this and this is uh so in our Docs as well in our Docs as well as our blog there's an this edit link so like people can jump directly into this edit view and directly like edit the file so there's like no friction there as well and no frictionless it could be even more frictionless because if they're not logged in the github but yeah and this is I guess another tip where if you do are using amyl and you don't want it cluttering up your github readme s-- you can just comment it out and then like on our build step basically I replace these comments with the yamo blocks and then it works in our static site build so that was lost does anybody have any questions or want to hear more okay so this was actually a huge inspiration for markdown magic this is a project called verb this guy man it's like some of those open-source contributors John Schlenker he's made like man probably like 5000 NPM packages insane it was this was an inspiration for markdown magic the way that this one works though is that you have to create a template file of you read me and then it generates it from that template file I didn't want to have to like maintain a template I just wanted to do everything in that markdown file and then the other one was oh so this is must have an honorable mention for ASCII Docs there are some people that really do like ASCII Docs because it has a lot of these plugins pluggable features kind of out of the box problem in my opinion with ASCII boxes nobody knows what it is and nobody writes it so you're really going an uphill battle when you choose ASCII Docs and you're like okay everybody write ASCII Docs and our community right ASCII Docs and learn ascii box basically so it is pretty powerful though i got a suite from one of the maintainer after I release markdown magic it's like why not ask you doc magic yeah but now you can tell them about markdown magic yeah so that is our our crazy setup in a nutshell I don't think it's too crazy though

Channel: Netlify

Views: 840

Rating: 5 out of 5

Keywords: jammin, markdown, david wells, jamstack, jamstacksf, meetup, san francisco, serverless

Id: LcgPRe7rLT4

Length: 39min 36sec (2376 seconds)

Published: Thu Feb 23 2017