Introduction to Markdown
Markdown is a lightweight markup language created in 2004 that uses plain text syntax to structure documents. It is readable in raw form and can be converted into formats like HTML or PDF.
Why Use Markdown for Developer Content
Markdown keeps authors focused on content rather than formatting and integrates well with version control systems like Git. It supports code blocks natively and is widely adopted across platforms such as GitHub and Stack Overflow.
Need for Markdown-to-HTML Conversion
Raw Markdown cannot be directly rendered as styled web content. It must be converted into HTML elements to enable proper styling and presentation in a web application.
Using Goldmark in Go
The video introduces Goldmark, a Markdown parser written in Go, to handle Markdown-to-HTML conversion. It supports extensions such as GitHub Flavored Markdown, syntax highlighting, heading IDs, attributes, and custom rendering options.
Parser Configuration
A Goldmark instance is configured with extensions for syntax highlighting, line numbers, tab width, and styling (e.g., Groovebox theme). Render options such as hard wraps and unsafe rendering are also enabled.
Implementing Markdown Parsing
A Go function is created to convert Markdown content into HTML using the configured parser. The function handles errors and returns the resulting HTML as a string.
Handling Safe Rendering in Templates
Because the templating system escapes HTML by default for security, a custom wrapper function is implemented to mark trusted HTML as safe. This ensures that parsed Markdown renders correctly in the browser.
Final Result and Next Steps
After integrating the parser and safe rendering wrapper, Markdown content is successfully displayed as formatted HTML with headings, lists, and highlighted code blocks. The next step is improving the site’s visual design and responsiveness.
So before we focus on making this site look like something we can actually show to users, we need to deal with this. And this is Markdown. And it's a really nice way of writing, especially for technical content, but we can't present it on our page like this.
Let me jump you into the terminal and then we can see what this article looks like in our markdown file. Then we will walk through what markdown is and why it's really good for developer articles. Okay, so here I have taken one of our dummy data seed data articles and put into our markdown file so you can see what it looks like in the terminal. And if you're not familiar with markdown, it's simply a lightweight markup language that was created in 2004.
that uses a plain text formatting syntax to create structured documents. It's designed to be readable in a raw form while still be convertible to formatted output, meaning that we can take this because it follows a set of rules and turn it into other things, right? That could be PDF files, but in our case, this will also be HTML elements.
I really like using Markdown for writing my articles because it keeps me focused on the content rather than the formatting. It's easy to integrate with what you see is what you get editors. It integrates maybe seamless into version control systems like Git. So that's also why I got very used to working with it. This is typically used in like developer documentation. We have stuff like code blocks being first class citizens. So if you want to showcase
Some code for some article we are writing, right? It's very easy to make it look look nice as well It's also platform diagnostic it's platform agnostic it's widely supported across Platforms like github, gitlab, Stackoverflow, whatever whatever you have It's very future proof since this is just plain text files So even though we are storming in the database you could
You could take it and save it in an R2 bucket or S3 bucket. You could even ship it locally with your binary if you didn't want to have a database, right? So it's a very good format to learn and to start working in if you're working in tech, because it is a widely used writing format. So this is one of some of the many reasons why we are gonna be using Markdown, but we can't ship
what is currently on the page. But we need to convert it into HTML elements so we can style it and make it look good on the page. And for that, we are going to be using something called Goldmark that handles the transformation from Markdown to HTML, as well as highlighting and code blocks and all of these kind of things. So let's
Let's set up this goldmark library and then we can start parsing our markdown to HTML elements. Okay, so I'm just quickly gonna show you the package of the library here. It's called goldmark and it's a markdown parser written in Go. Again, you're sticking to Go as much as possible. It's easy to extend, which we will see. And it simply just provides us with the
with this conversion from Mac down to HTML. So check this GitHub repo out if you want to. It's very easy to work with. So this is what we're gonna be using. Let's actually jump into the code and start properly converting our articles. Okay, so I'm just gonna jump into our views package, an article, and in here we're gonna be needing a bunch of
import. So I'm just going to add these and then we can walk through what we are doing. So I'm going to add them here and then I'm also going to add the whole setup for the parser. So we're going to say var markdown parser equals to all of this. When I give this a save, jump out, say compile views and then go mud.
So we get all of the packages downloaded to our Godot mod file. And then if we jump in to articles here, we have no errors anymore. Okay, so we create a new instance of goldmark. To specify, we want some extensions. We want to use the GitHub flavored markdown extension. We also want some highlighting for our code blocks, which is what we define here.
We're going to be using the style of Groovebox, which is also what you see in my editor here. We also want some line numbers in our code blocks, and we want a tab width of four. And then we simply add that we also want some headings IDs. We want some attributes. And finally, some render options here with some hard wraps and with unsafe. So this one, yeah, it renders dangerous content, but it's our content right. So it's fine.
And this is all we're going to need for our purposes now, but you can add more tool. You can change it. So I definitely encourage you to check out the Goldmark library or GitHub repository. You can also check out some of the other repositories to see what options are there in terms of styling and formatting and options. You can do a lot with this. Great. So now we have the parser, but we still need to create another function here.
And only in all of this is, you know, it's go, so we can just write perfectly standard go. So let's create a function here called pass mark down to HTML. We're gonna pass in our content and we're gonna return. Let's simply just return a string here. So we're gonna say, we're gonna have a variable called bar HTML out. Put.
bytes buffer, if error equals to mark down, mark down, parser, convert. It takes in a bytes slice, so we're gonna say bytes slice and parse the content we receive, and then we're gonna output it into our HTML output. HTML output. If there's an error,
We're gonna say return, could not pass article. So, oh, ever is nil. Again, this will show up on the page if we do something wrong. So we need to, we need to be careful here. We could also technically make it something went wrong. Please, please try again.
But if nothing goes wrong, we're going to say return HTML output string. And no, we don't have an error. We just have this, right? So we could do this. We could also do this in the controller layer, and then return an error page to the user. But this is effectively the same thing that's happening, right? Because we would always return a 200 response with an error page.
So in this case, we can see something went wrong and we need to be careful what we do. Then we can say pass markdown to HTML. And if we now go ahead and say just run, do we have an error? We do have an error. What is the error?
We are doing something wrong. What are we doing wrong? We are doing nothing wrong. Could not import bytes. Okay. Let's just run it one more time. There we go. So let's jump into the browser and see what happens. All right. So here in the browser, let me give it a reface and see what happens. We have a bunch of a HTML, but it's not rendered at all.
This is a safety mechanism from Temple's side so that we don't get injections into our markup that we're not supposed to have. So we actually need to have another wrapper to say this is actually okay. So back in the terminal one more time, we're gonna add a function called unsafe. It's not really unsafe because it's our, we are the ones that are delivering the content right. And then we can actually see the markdown showing up.
Okay, so the function we are going to be needing here is going to be called funk on safe. Just to be very explicit, it's going to receive some HTML and it will return a Timbal.com component. So we're going to say return. And now we can rely on some of the functions from the Timbal library component, component funk, where we're going to add another funk.
We need some inputs. So let's just get those out of the way. Con text and IO. And in here, you're going to say error equals IO. And we're going to use something called a write string that takes an IO writer and a string, which is our HTML. And then we're just going to return. So.
Give this a safe. And do we actually, we need to do this and return. We don't have enough return values because we need to return the error, of course. There we go. Now we can wrap this in one more function saying unsafe.
And this needs to be no. I am. Yes, this needs to be because this is a temple component, right? Yeah. So whenever we're dealing with temple component, we need the, the at the at symbol here. Great. Let's jump out. So you just run, jump into the browser and see what happens.
All right, let's give this a refresh and hope that everything actually changes now. Wow, there we go. This is starting to look like a block. You can see we have headers, we have code blocks that is actually looking quite decent. We have on-order lists. Yeah, so this was a very fast way to deal with
converting something from Markdown to HTML. So we have a nice writing format and we can also present it in a nice way. In the next module, we are going to be tackling with this look and feel of this site where we can make it look good. We can make it fit across screens. Yeah, but this is basically all you need to convert from Markdown to HTML. Yeah, next episode, let's tackle this UI because this is also starting to be hard on the eyes.
