The Build

The technical build with Gatsby

This process was probably the most exciting for me. I've been spending the last couple of years taking various Udemy courses and watching random Youtube tutorials brushing up on my development chops. Primarily focused on web development, I've gone down the rabbit hole of learning Javascript and a library built on top of it—React. For this project I mentioned I'm using Gatsby, which is another framework built on top of React.

There are a couple things I want to mention right from the start:

1. I actually did build this blog in a month. The design and the technical build. I'm finishing writing about it exactly one year later. Life happens. The spirit of the blog is also transparency and what someone can realistically accomplish. This whole build from idea to inception is totally possible. I just haven't been a committed enough writer so this has been on the back burner—which leads me to point number two.
2. I also haven't really looked at the code in exactly one year. If you have ever written code (or in general have learned something new) you would know coming back to that thing a year later without looking at it can be a tough pill to swallow. I have been able to jump back in and add some stuff pretty easily—so that's promising.

Both those points are just to say that the following post will not be a direct representation of exactly how things went down. I'll do my best to give you some highlights of how I went about this thing and my thinking. But if you're here for deeply technical post, I'm afraid I'm going to disappoint you.

The Build

All of my code is being written in a code editor called Visual Studio(VS) Code. At the base level the technologies I used to make this are HTML, CSS, Javascript (Gatsby/React as a framework and library), GraphQL and MDX (which is Markdown with JSX capabilities). I'll walk through at a high level what everything is.

MDX

I write all my blog posts in MDX. Like I mentioned, it is a specific version of Markdown with some added technical abilities—JSX to be specific, more on this in a bit.

The tool I use to write my posts is a sleek one called iA Writer. It's a really great way to do some focused writing and be able to write in Markdown specifically. After I write it there, I send it over to VS Code in order to add some additional bits of code if necessary.

Markdown is a markup language (what) that lets you add formatting to plaintext. Diving deeper into what that actually means, instead of the fancy built in formatting tools you may be used to in Google Docs or Microsoft Word—like clicking buttons to bold and italicize text—in Markdown you specify how you want words to be treated in regular text. So for example if I want to italicize something I add these characters around the text _ _ and if I want to create a headline I can use #.

Why even do this? Isn't there an easier way to just write stuff? How does this translate to a website? Is it this hard to just build a blog? Woah, woah, woah—take it easy, we'll touch on all that. The reason I'm doing this is because I'm not using a CMS (content management system). In a typical CMS—something like Wordpress—you can have a built in fancy text editor like you're used to. It will have you fill out all the relevant info you need display a headline, images, and any additional info that is important to your blog. The reason I didn't opt for that route is because what I mentioned earlier—the added technical capabilities. Behind the scenes, the code is telling the browser how to take in all the Markdown and display it based on all the rules I set for how I want things to look.

The added special sauce in MDX is JSX (MDX = Markdown + JSX). I'll talk more about JSX when I get into React, but what this is letting me do is write code directly within my text. It lets me utilize certain HTML tags and functionality and also allows me create custom components (remember the idea of components from the last post? ) that I can just plop into the middle of my posts as I'm writing. I wanted this extra flexibility because honestly I have no idea what I'll be writing about in the future.

Let's say for example I write about cooking and I want to build a cool recipe card, and don't want to fuss too much about how to get that to show up where I want to—and I also don't know if I'll ever use it again. I just build the logic for the component, insert it right in the middle of the text and give it the properties I want it to have, and all the rest of the magic works behind the scenes because of the plugins I have working with Gatsby (more on this in the Gatsby section).

The last parts of MDX and Markdown to know about are Front Matter and exports. These two parts are things you can't physically see, but the data provided by both of them are really important and help populate everything you are seeing.

Front Matter is a special block of key/value pairs defined in a Markdown file that exposes data that is relevant to that specific file. All of my posts have relevant info that is needed by components in the application in order to function how I want it to. This info is needed for things to be ordered in a specific way, to display things where they need to be, and in general make things work how I want them to work.

A concrete example of this: in order for the posts in a series to be ordered in a certain way—I define a "postNumber" key in the Front Matter of every post, and the value that starts at 1 and goes to whatever the last post number is. This is then used later in the series page to make sure that the posts are ordered sequentially and not just randomly.

Here is how the Front Matter is structured from the last post:

The next part—exports—is a way for me to expose more detailed data. The resources, tools and costs section all are very specific to each post. They have text and links that are defined in this exports section, and exposed for the rest of the application to use.

Here is how it is structured in the last post:

Cool. So I'm writing everything in a version of Markdown with some special magic to add components. I format all my text based on seemingly arbitrary characters. There is some additional data I define that is relevant to the application but isn't user facing. What happens next?

HTML, CSS, Javascript, React and Gatsby

These technologies are the next piece of the puzzle. Each one of these have mounds and mounds of technical writing and people who can explain it to you super granularly if that's what you're looking for. I'm just going to walk through what these things are and how the pieces work together to spit out what you're looking at right now. Lightning round explanations starting now:

HTML is a formatting language. It's the building blocks of how websites are structured. When you see a headline, paragraph, section of a page, picture, literally everything else on a web page, there is an HTML tag that denotes exactly what the piece of content is.

CSS is a rule-based language that describes what all those pieces look like. It's what gives you the colors, the different typography, text size, position of each element, literally everything that has a style is defined in CSS.

Javascript is a scripting language and is what gives the logic and functionality of all the elements on a page. Clicking on a button that takes you to a page, data on a page being dynamically updated, the ability to actually collect data from an input field when you sign up for something, literally everything that is interactive and actionable.

React is a Javascript library that helps organize and conceptualize the idea of atomic design. Its purpose is to streamline creating interfaces by breaking larger chunks of code and logic into components that do very specific things. You then use those to build bigger applications and websites while defining how data is handled and stored.

Gatsby is a framework that nicely bundles all the tools and technologies being used to create static sites. Through the use of various plugins and configuration, Gatsby combines all data and content to build the site and optimize performance. The important tech issue to note here and why I didn't use a different framework is that Gatsby relies on the data being present at build and it is rendered client side. All that means is that I am not using dynamic data in A Month Learning. No realtime input that could change how the blog looks or functions. I do everything on my end, push the code where it needs to be and let the rest of the magic happen.

GraphQL is the last piece of the puzzle. It's a query language that's used in order to get data flowing throughout the components and application. It's the central spot where data can be queried from multiple different sources and be made available when it is needed. It's a very readable and developer friendly way to ask for specific pieces of data that is relevant for the given component or page. Gatsby specifically uses GraphQL by enabling special components that declare what data is needed. Gatsby packages up that data and makes it available in the browser.

So those are all the individual technologies used to create everything that you're seeing at a super high level. Next, I'll go through an overview and talk about how these things are working together to show you what you're seeing.

The Magic

Now that we have an understanding of all the tools being utilized. How does it all actually come together to make a website?

For this website, everything is written in React, and then a bunch of behind the scenes configuration takes care of converting things to HTML and CSS so the browser can spit out what it needs to. Components are given specific logic that perform specific tasks. They are also given rule based properties to position them on the page and give them the styles that make them look the way they do. The components define what sort of data they are looking for, and when they get that data they do what they're told to do with it. Most of the data is defined in the Front Matter and exports of each individual MDX file, and are extracted through GraphQL queries.

Components live in a specific file. Once they have the logic and are all packaged up, they are exported from that file and imported into either larger components that are built from smaller components, or imported to a page/template that will display all the final components.

Now to conceptualize all of that. The page you're looking at is a template file that lays out the structure of the page and passes down relevant data to each individual component. The navigation at the top is a component that is made up of smaller link components. The "Share" and "Resources" sections are components that are filled with data from the MDX file's Front Matter and exports. The section with the actual content is a component that parses the MDX file and displays it in a certain way. The "Subscribe" section is a component that is built from smaller input and button components and handles taking data and sending it to another service.

And that's really it. There are obviously a million other things that are happening, but that's really the mental model of how I visualize a lot of this. The rest is just figuring out the specific semantics to make it happen.

If you have any specific technical questions or comments, feel free to send me a DM on Twitter!

A Takeaway

Quick detour away from the tech, because I really wanted to end this with something I've learned through this part of building the blog. It's about learning in general. The most important resource for learning all of the stuff I talk about in this post was a fella by the name of Andrew Mead. I really don't even know how I found him, it was probably just a search for a specific topic in YouTube. But his courses cover literally all of the above technologies in a way that really made sense for me.

I spend a lot of time reading documentation, watching various tutorials and fiddling around with stuff. As a lifelong learner, one takeaway I consistently find to be extremely valuable is to really find someone that explains a concept in a way that clicks for you.

You can read, experiment, listen, and stumble your way through anything. But once someone can take a concept and explain it in a very specific way to connect all the dots in your head, or you're able to see someone perform an action in a way you know you can replicate—you really realize how important it is to find that person.

To me, this is arguably the most important step of continuing to push through roadblocks and it isn't talked about nearly enough. If for some reason you're not able to wrap your head around something, I'm willing to bet it's because you haven't found someone who really can distill it down for you.

So if you care about learning something, don't be discouraged—just keep searching for that person or persons. The more dots you collect in your brain within a specific area, and the deeper you dive into that subject, the more likely you'll stumble upon someone who can really help connect it all.

For the next post I'll dive into the final part. Now that we took the design and built it with some cool technology, we have to figure out how to launch this puppy into the world.