GitHub Open Source Friday, 26 Jun 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How Stripe Powers Their Documentation with MarkDoc - Open Source Friday #opensource

Description

Recently, Stripe open-sourced Markdoc, the content-authoring system that powers the Stripe docs. You can now freely build documentation, static pages, or tooling with the same tools Stripe uses: https://markdoc.io.

In this video, Developer Advocate at Stripe, Charlie Gerard gives @blackgirlbytes the run down on how Markdoc works. Learn how you can use MarkDoc and how you can contribute to this open source project.

0:00 - Introductions
2:29 - What is MarkDoc
3:20 - MarkDoc is for more than just documentation!
6:35 - Creating Custom Banner Components
7:43 - Debugging Doc Sites Made Easy
9:19 - Defining Variables
9:41 - Defining Functions
11:06 - Programmatically uppercase doc elements
12:06 - Handling Validation in Markdoc
15:53 - Why did Stripe open source Markdoc?
17:59 - Q&A
20:12 - How to contribute
22:09 - Can I use Markdoc with GitHub Pages?
24:32 - Favorite food
24:43 - Favorite Beyonce song
27:16 - Charlie plans to create MarkDoc tutorials

Join @blackgirlbytes live for Open Source Fridays at https://www.meetup.com/github/.

Thanks!

Connect with us.
Facebook: http://fb.com/github
Twitter: http://twitter.com/github
LinkedIn: http://linkedin.com/company/github

About GitHub
GitHub is the best place to share code with friends, co-workers, classmates, and complete strangers. Millions of people use GitHub to build amazing things together. For more info, go to http://github.com

A

Yeah, I'm super excited to have you here. um I think it's cool, like everybody, was really excited at the the fact that mark doc got open source. Would you like to just get us started and uh tell us who you are.

B

Sure uh so I'm charlie gerard I'm a dev advocate at stripe. So I only started three months ago, so I'm still learning about all the the different products um but yeah like on the side. I I love technology in general, so uh you know advocacy is a good role for me because it's like about teaching what I learn and then I also uh explore a lot of different javascript stuff on on the side as well. So yeah, that's very, very short description of who I am.

A

Oh, I love it. I love it and I like started recently too. um I don't know how long ago did you start into in developer advocacy.

B

um So I'm mean my last job, the last six months of it were also advocacy, but.

A

B

Let's say as a job: I've done it for maybe a bit less than a year, but I feel like I've been speaking like at conferences and doing things like that for quite a few years now, but it wasn't, I wasn't paid for it.

B

So I was more of like a general advocate, uh but it wasn't my job title yeah.

A

That makes sense, because I remember seeing you on twitter and you were doing like stuff with tensorflow. I thought you were a developer advocate then um I was really looking into developer advocacy. So that's awesome and I feel like that's how a lot of developer advocates get their start like they start off. You know kind of showing off what they're what they're up to and then um they eventually transition into that. Let me see. There's some comments: hey prince uh princes.

A

Like it's gonna be a netlify, a little mini netlify reunion, yeah and also hi. uh I don't know how to say your name. Look lacampson. Is that your username cool but hello thanks for joining us and everybody else, who's viewing us.

A

We could jump straight in if you're, okay, oh lake, okay, cool, thank you so much. uh We can jump straight into the um what is mark dock and then the demonstration I admittedly had never heard of markdock before you all over sourced it. So I would love to to learn a little bit more.

B

Sure so uh magduk is the authoring framework that we've been using inside stripe for a few years to build our documentation website. So if you go to strike.com docs, uh it's built with with macdoc, so it started being built uh way before my time. I only joined stripe three months ago, so um so yeah mcduck had been built internally as like a private repo for a few years before that, and we've decided to open open source it recently to get more contributions from people and knowing that, um I think a comment.

B

I've heard a lot when I joined stripe is that oh, the docs are amazing, so it's like sharing back to the community and helping other people also be able to uh build. You know really big documentation, websites that are also interactive, and I think that so.

A

B

You you can do more than just docs with macduck, but that's what we've been.

A

Using it for oh that's,.

B

A

Cool, so you don't have to use it for documentation, but that's like one.

B

No yeah, you it's it's more about authoring, so anything that has content can be built with macdoc. So you can. You know I'm considering rebuilding my blog with magdala, because at the moment I'm using gatsby, but I feel like nsp is like too much for my blog. I could kind of like stream it down to um like strip it down to to only using because I'm using markdown files in for my blog, so I could only like use macduck and not have to to use gas b with it. But I was thinking about different options.

B

I think that could be built with magdalk and you could have a design system built with macduck as well, because it's a mix of markdown and um and components. So you know I was thinking about an interactive learning tool or anything that has content and that you can add a bit of uh like extra functionality to it can be built with with mac doc. For sure that's.

A

So dope I'm gonna have to try that out. I thought it was just for um documentation, but like now you're you're, having my my wheels, been spinning in my head quickly, hi to um aj. He just said: hey mark doc looks super cool, also lawrence just joined in, and then I don't know how to say your name, but I'm gonna try ravid singh biz thanks for joining us, too. um Okay cool thanks for telling us a little bit about mark dock and y'all this. This um stream is gonna, be super short.

A

I'm trying to have these be like little little quick bites. So I would love for charlie to just show us like how how it works or demo or.

B

Something yeah sure. Let me just share my screen. Okay, oh and so I oop sorry, no.

A

I'm sorry sorry h, I get distracted easily. I saw a comment he um he uses mark dock for literally everything. He writes um everything in oh markdown. I think they said mark dock nevermind.

B

But he's well, if you use markdown for everything you can use macduck for everything.

B

Yeah, so I just wanted to share quickly, um there's like a a little bit so for one when we launched uh magdal publicly, I built a simple nexus starter uh and for this stream today I did a few things to kind of show you a little bit how it works. So hopefully you can see um the screen, but if you go into the main macdog repo and you look at the starter, you will see a page that looks like this and on the main index.md file, which is like this page here.

B

You can see that you're writing it. uh The core of it is markdown. So it's you know built you know as an extension of back down. So if you already have a lot of markdown files, you can use them with uh with macdoc, so um that you know that's not anything new, uh but if I you know, if you go to the uh introduction page that you know I just built. One of the thing that is a little bit different is that you can define a front matter here that you can that you can use.

B

If you want to define uh the title- and uh one thing that I wanted to talk about, is how to how we use components so here if you're used to using standard markdown, you can't do actually something like this, because what this is here is a custom banner component. That's like a react component in which you can pass a prop of type warning, and what is displayed is like that. One here.

A

B

Yeah, so the way, the way that we can do that here is that, if you know react, that's like a standard banner component that renders children and there's like some styles here and depending on the type that I'm passing, I'm applying a different background. Color, so that you know that's not something, that's super complicated, but it allows you to then use these components in in markdown and the way that you do.

B

This is um usually the the way that we want to structure apps is that you have a macbook folder and you would have a tags file in which you import your banner component and you export it that way by defining the component that you want to render.

B

So here are banner and you define the types that you allow people to pass down and you can say: okay, uh I want people to be to pass a string so that, if you pass a number, you get an error and you can, you know, define it as required, uh true or or false, so that it allows you to avoid rendering content that's broken. So it's kind of like sending up some guardrails um so so that you can help people know what they can and can't render, because I think in general, with docs documentation websites.

B

It can get to a point where it's so big that there's an error somewhere and especially if you're collaborating between engineers and more like docs engineers, who are more focused on actually writing the content and thinking about the information architecture. They don't always look at or they don't know, always like how to fix the actual structure of the site.

B

So when they, you know, come to you and say, oh well, I broke something it's very hard for me, actually to know what is broken or where, where the issue was actually introduced and uh with the the components that you can build with macduck. You can say um here that you want this type type to be a string, uh and you can say that it's required or true so that true or false- and you can have more that I'll show a bit a bit later.

B

um But it's like one way to make sure that uh you don't actually merge broken content. It can kind of like guide um people so that you can collaborate between people who are more purely writers and um and you as an engineer as well so um so you can use my doc in different ways, so I've showed like markdown files, but you can also write your markdown content in a javascript file. So if I go back and I show the resource page, uh this is like very very, like small design right.

B

You can all do better than that, um but it's the the way that you um that you would so I'm sorry. Let me get back so there's like a few more things that you can do where you can create some variables, and so here the name is brazil uh yeah, and you can pass some like functions as well and the way that you have your your content. You can define it like here. So, for example, if I write uh so the name that would be the name of the variable, then I have like result.

B

So I can say result is awesome and this is how you would uh like reference your variables. So you can see that if it's a tag then there's no dollar sign. But if you refer a variable, you have to use the dollar sign and uh in the way that then this config object is passed down. So you parse your content to create an abstract, syntax tree, and um so valida is for just a bit later. But the main thing you have to do then, is to transform it.

B

So you pass the abstract syntax tree to the transform method with the config to say: hey, you're, going to look at all of this content, but you're going to have to figure out what this name variable is where I defined the the component etc, and then you render it with the well. I mean using next here. So it's a react renderer, but we also have an html renderer and I think we're looking for contributions. If you're using vue, you might have to create a view renderer.

B

I think we don't have one for spelt as well, so um it's kind of like we want people to be able to use magdoc with a lot of different tools, and at the moment we have a react renderer, because our docs uh website is built with with nextgs, so we needed mainly a rack renderer, but um but yes, you can do that in here, like I had a uppercase functions that I defined in my functions, folder and what that takes. It's like it takes the string that is passed to it and it returns.

B

You know uppercase. So if I want to say, uh result is awesome in uppercase, then- or I would just let's just do this one, then I would do like uppercase and then I say what like awesome and then it's like result is awesome, so yeah.

B

So it's this way of being able to add some kind of like functionality to your your markdown. Make it more modular, um and one thing that I wanted to that is probably one of the most interesting thing, I think, is the fact that in the attributes that you can pass in, you can say what you want. Certain properties to match so here, uh for example, I have a banner and I pass type alert, but here my banner, I only want to allow people to match info or warning.

B

So what you can do here is that if you call validate and you log the errors, uh there's gonna be an error here that is rendered in. I don't know if I can zoom in for people um and what you get in your console is that it tells you well, the attribute type must match and I might have to make that bigger.

B

Okay, it must match info or warning. So what you can do, then, at the moment, I'm allowing the content to be rendered anyway. But um what you could do is prevent people from being able to to render the content when you could display something. uh You know for your docs engineers that say: hey you passed in the wrong uh the wrong type. So and if I say type you know warning, then all of a sudden I have no error and I'm applying the styles that I defined before that's.

A

B

Very quickly, that was kind of like all of the things that I don't have much time to go that much more in detail. uh But this is like the type of things that you can do. You can extend the capability of your markdown files with in a few in a few different ways and then play around.

B

uh You know like one thing that I like on the striped docks is how your api keys are populated, so you can directly copy uh the the code with your with your api key, instead of having to like find it out somewhere else on the dashboard.

A

um Wow well, I.

B

Can't show you right now otherwise you're going to see my api keys, but.

A

B

It's uh like you, you can. If your users are logged in on your platform, then you already have data about them, and uh you can populate that in your in your markdown to make it a lot more interactive and try to create better uh docs experiences, but again it's not only for docs. This is why I really wanted to try to build some kind of interactive learning platform where you could have you know you could ask um a developer to like write a piece of code and then using the the validate method.

B

You could check if they're actually doing the exercise properly. For example,.

A

B

Yeah, that was like a lot in like five minutes. Hopefully it gave people some ideas, but yeah.

A

No yeah, I mean you're, giving me ideas, I'm like there's so much projects I want to make now. This is really awesome. Thank you and I love how they have like. um So many I don't know the word, but so many things in place to make sure that you don't make those those regular mistakes that you can make in documentation like you were saying, like catching different bugs. um I really love how they designed that.

B

A

Yeah, it was really.

B

Useful for us, because our docks are really big so to make sure you know to make it easier and basically prevent the errors before they happen kind of so.

A

Yeah, that makes a lot of sense. I mean you all have so many different apis, so many different use cases for stripes. So that makes a lot of sense. um If anyone from the the audience or the audience, I don't know what to call them. Has any questions feel free to ask, but but with the disclaimer that charlie did not maintain this project she's just an advocate that started a strike three weeks ago, but I'll I'll I'll highlight a couple things prince said this is so freaking cool.

A

B

Prince always so nice ellie.

A

Put some some fire emojis, um there's, there's people loving it. There's people, oh and prince, also said the docs. Don't lie.

A

You're, awesome too, charlie and and prince, um but it doesn't seem like y'all, have any crazy questions. um I have like one two small questions and one is like: do you know why um stripe decided to open source markdog.

B

um So I don't have the full background story, but I know that I think a few. Maybe I don't know if it was months ago. Last year uh we started open sourcing like another tool like a type, something called sorbet a type checker for ruby, and I think that we're slowly open sourcing more of the tools that we're doing internally, because we know that it can help other people. I think that um as a company as big as stripe, um you know can help a lot like in open source.

B

If there's something that works for us at the size that we are, then we can help that we can hope that it can help also uh other people along the way as well. It's like there's kind of no way. I mean no reason at some point to keep something private if it's a tool that other people can use.

B

So um I think we would love as well to uh be able to have contributions from the community as well, there's a moment when, so it could work. It works for us yes, but like it would be more interesting if we understood how it could work for other people too. So that's like one of the main reasons. Yeah.

A

One of the things I love about stripe is how much you all value open source like I was talking to to chris tragenos, and he was talking to me about like how much he valued like doing sponsorships and like yes, it's being sure yeah, I'm like more companies need to do that. Like.

B

We give a lot of money to people who build uh like github reports that are related to stripes. So if you want extra cash.

B

I'm not the one who picks the repositories, but I know that we are trying to help maintainers, because we know that we can't do it all and other people in the industry might have use cases that we don't know about, and uh you know the more people help um you know others get started with stripe product through open source. Then we want to be able to support that. We don't want people to do work that is unpaid, so yeah for sure yeah.

A

I want to highlight a couple of comments: hey hey lazar. First of all, I he said: congratulations on your new.

B

A

And then I think kevin put that party emoji, probably in a new job as well and um prince said I saw you, were working on some ultrasonic experiments with javascript. What inspired that, for you.

B

um I think that I want to explore, uh maybe because I know that you know when people think about payment, they're thinking like oh well, I'm paying for things every day like what can what else can be done with that and I'm interested in mixing my interest in like innovative technologies with the you know, financial sector, that, because I'm not quite familiar with that, you know the whole payment stuff like I'm, I'm the same, I'm kind of like I went into stripe and I had never really used trite before so it was it's like I'm just I'm trying to mix both, because I think that there are uh things that can that can be done uh with.

B

I want to try and mix like iot and payments like can you create a little like button, and that gives donations? I don't know something like that and uh with the ultrasonic experiment.

B

I came across like an article of a company that was doing that before and I was thinking well, you know if you needed to pay while your device is offline, like that, you know, using like sending data through sound means that you can. You can do that and there's like, maybe maybe in terms of security. It might be better because you can't have you could have like a man in the middle attack. Maybe, but I don't know how you work with sound uh but yeah.

B

So it's like trying to bring what I think I do well like this time, like experimental stuff with technology into um into stripe as well and see you know. How far can I push payment.

A

B

Things like that.

A

Yeah you're you're a developer advocate at heart, like I really want to get like you and like kobe, for up, I don't know if you know him, but y'all do like a lot of like different experimentations um and I'm like. I really want to get to that point. um People said that's so rad sounds so cool.

A

Also kevin's um comment on me. Sending a pr to mark docks actually reminds me another question: how can people contribute.

B

um So the repository is, uh is public now, so there's like an org, a mock doc. I can't send links right now, but maybe I can send them to you later, but it's um so. You have mgdoc on github and uh there's like a discussions page. If you look at the repository and we welcome either like questions or you know, comments feedback if you do build something, there's like a little show and tell tab.

B

uh So if you build a macdoc plugin to work with a tool that we haven't supported yet, yes, thanks thanks for sending the link, um then you can uh you can share it with us and you know we'll highlight it. We you know stripe sends like a newsletter as well, uh I believe monthly, and uh we want to highlight the work that other people do as well. So definitely everything is uh is on github and it's quite active. There's like a dedicated person uh on it.

B

So uh I'm really excited to see what people end up building with it, especially with the types of things that can be built. uh I would love to know if people end up building their docks, using mug dogs or or building some design system or or whatever like I it's like, I'm always interested in seeing how far you can push things. So I want to know like. What's the weirdest thing you think you can build like I'm interested in this. I think that's what I'm gonna, I'm gonna explore um so yeah.

B

Definitely through github people can um can ask questions there and contribute.

A

Awesome yeah y'all heard go to github.com.

A

Look at the discussion, look at the open issues and try to build something awesome. We do have a question. I hope that like if we don't know the answer, that's okay, uh someone's asking: can you use mark dock with github pages.

B

So I haven't tried, but I believe that, because github pages it has to be yeah, it's static right, so I'm wondering if you can use, uh I think what you could do is you could build. um So you could use macdoc to build like to create your content and then have a build comment that generates an index.html file. That would then be rendered in github pages.

B

So I believe that would be uh possible, but I haven't tried, so I can't tell you exactly how, but this is what how I would go about it probably uh spin up. You know maybe like a next app and then um I don't can you well. Maybe you wouldn't know that result.

A

Can you define the path.

B

A

Indexes, okay, just to make sure mark dock doesn't have like a back like you, don't have to have a back end with it right because if that's the case, okay cool, if that's the case, basically actions build out github pages now, so um you can go into there's a couple actions that, like help you to easily render um next js site to react and or you can just edit the action that like builds the github page and just go, um tell it to run.

A

What's I forget the command that basically generates a out folder with index.html um for a next.js site.

B

But I've done it, so I think that would be that would be possible. Then I think.

A

B

Need a back-end, but as it's using javascript you need to it's just like a you need to be able to install packages and and do your code, but once it's built, then you can render it. You know on a html file. I believe.

A

Yes, exactly and lazar just reminded me: it's like export, I did it before um I'll need to maybe after this I'll, like tweet out the the project that I used, um it's the next js site that I use to build that out like you, can you can do it? I just forget all the stuff you can.

B

A

um Cool all right, so I'm gonna wrap up with some non-technical questions so that you can chill and now hopefully this chill so my my my non-technical questions are: what's your favorite food and what's your favorite beyonce song.

B

All right, favorite food- I love nachos like if it was healthy, I would just eat nachos um but and favorite beyonce song. I really like halo. I think it's because there's a bit of like piano in it and I wanted to be able to play it, but I mean I bought the keyboard and I have had no time to play, but.

A

B

B

That's awesome, maybe maybe you know when I have more time I'll, be playing a halo by beyonce, but not today.

A

Better than me all, I know how to do was chopsticks from first grade there. I was like that's too good, you know.

A

um um Let me see someone said it's not healthy about nachos. I mean.

B

I mean you know, there's a bit of, I mean well, okay, you could say: there's a bit of meat and a bit of veggies but like, if you add sour cream, it's over and cheese. I mean.

B

A

On the look for nachos, though I had I had one year where I was obsessed and lazarus. One of his favorite songs is the one where he smashed it. She smashes the whole um neighborhood with her back. Is that sorry? I don't remember it's on she's wearing a yellow dress. I know what you're talking about someone said so wholesome awesome. Thank you. So much charlie, I feel like this was really fun.

A

uh Thank you. Everyone for tuning in I like to just keep these short and just like see the demo chat a little bit and then um we could leave. Do you have any like last um thanks thanks lazar that you love this stream. Do you have any last things that you want to promote, maybe like- and I should have asked this before like want people to follow you on twitter or dev, dev, charlie or anything if.

B

They want to like no pressure.

A

Yeah, no, I I'm pressuring them you have to, and she has some awesome content that she.

B

I just want yeah thanks thanks everyone for for joining, and um you know again. I think what I, what is good, I think about markdog- is that it's still, I don't think it's even I don't even know if we have like version one. Yet I think it's like we just started uh open sourcing it. So there's a lot of things that haven't been done, which I think is a great way to get into open source.

B

So it's still at a stage that it's small that you don't have you don't need that much context to try to you, know, understand and contribute. So, even if there's something that doesn't make sense in the docs or something that you would like to see more of uh feel free to start a discussion, I want to start creating more tutorials because I think that's like so far.

B

I've only created two blog posts, so if I you know, can understand what people struggle with and that helps me then make sure that I create stuff that um you know make it more easy for people to understand. So if you have some time- and you want to- uh I think it's a good like small repo to get started.

A

Yeah, it's awesome y'all. You heard it here like it's a perfect boss to start at before. It's too big, like I don't know if anybody ever tried contributing to the react project that one's hard. So this is a good, a good first like starter um for people um awesome. Thank you so much charlie for coming in and talking. Thank you especially also short notice. I appreciate you um and I appreciate you all for listening in bye.