DEV Community: Liam Clegg

The Secret to Fast Typing on the Game Boy: Here’s How I Did It!

Liam Clegg — Thu, 24 Oct 2024 19:56:36 +0000

Repository : https://github.com/cleggacus/gbos
See it working : https://www.youtube.com/shorts/qvXVCzCBPLs

The Quest for Speed: Why Fast Typing Matters!

In the fast-paced world of gaming and technology, efficiency is key. Imagine trying to navigate a complex menu or communicate in a game using a slow, cumbersome typing system. It can be frustrating, especially on a device like the Game Boy, which has a limited number of buttons and a small screen. This is where the quest for speed comes in!

When I set out to create a typing system for the Game Boy, I wanted to address these challenges head-on. Traditional input methods, like QWERTY or ABCD keyboards, are great in theory, but on a non touchscreen handheld console or TV keyboard, they can feel clunky and slow. Typing out messages or navigating menus should be quick and intuitive, allowing people to use the software without being bogged down by the mechanics of input.

Enter T9 predictive text — a system originally designed for nokia phones that allows users to type faster by predicting the words they intend to enter based on a few key presses. By adapting this concept for the Game Boy, I aimed to create a typing experience that was not only faster but also easy to learn. The T9 method offers a way to maximize the limited buttons available, letting users express themselves efficiently without breaking their flow.

From Concept to Code: The Birth of My Game Boy OS

The idea was simple yet revolutionary: instead of relying on a standard keyboard layout, I would create an on-screen keyboard that utilized T9 technology. This meant that each button on the Game Boy would correspond to multiple letters, allowing users to type efficiently with just a few presses. For example, tapping the number ‘5’ — located conveniently in the center of the D-pad—would be the main action button, letting users select words suggested by the predictive text system.

With this concept in mind, I set out to develop the foundation of my Game Boy OS. I decided to use C as my primary programming language, leveraging the Game Boy Development Kit (GBDK 2020) to tap into the console’s hardware capabilities. However, I knew that for certain performance-critical tasks, I would need to incorporate Assembly (ASM) to optimize speed.

To tackle the complexity of predictive text, I opted to generate a trie data structure in Python. This would allow me to efficiently store and retrieve the words in my dictionary while minimizing memory usage. With a target of 10,000 words, I aimed to create a compact yet comprehensive dictionary.

Embracing the Classics: Using a Real Game Boy

One of the most thrilling aspects of this project was the opportunity to work with authentic hardware: a real Game Boy. The tactile experience of typing on the original device, coupled with the nostalgia of classic gaming, added a layer of authenticity that simply can't be replicated with emulators. The Game Boy’s iconic design and sound, along with its limitations, presented unique challenges that enriched my development journey.

To facilitate this project, I utilized the EZ Flash Jr., a flash cartridge designed for the Game Boy and Game Boy Color. This cartridge not only allows for the convenient loading of custom ROMs but also supports save states, making it perfect for development and testing. With the EZ Flash Jr., I could quickly transfer my compiled programs to the Game Boy, experiencing firsthand how my changes affected performance and usability.

Crafting the Brain: Building the Trie in Python

In my quest to enhance typing speed on the Game Boy, I needed a robust structure to manage my dictionary efficiently. Enter the Trie, a tree-like data structure perfect for storing and retrieving keys in a dynamic set. I opted to use Python for its simplicity, enabling rapid prototyping.

The process began by defining a Node class that represents each character in the Trie. Each node contains pointers to its children, a completion flag to mark the end of a word, and a score to prioritize suggestions based on usage frequency.

Here’s a snippet of the key methods from my Node class:

class Node:
    def __init__(self):
        self.complete = False
        self.children = [None] * 26  # For each letter a-z
        self.child_counter = 0
        self.score = 0

    def push(self, val: str, score: int):
        # Logic to add a word to the Trie

Using Google's 10k dictionary as my data source, I iterated through each word, adding it to the Trie while calculating a score based on its position. This scoring mechanism helps prioritize more commonly used words, making the typing experience even smoother.

The culmination of this stage was a serialized version of the Trie, ready to be converted into C code for the Game Boy.

Translating Ideas: Encoding the Trie for Game Boy in C

Once I had my Trie structured and populated with data, the next challenge was translating it into C to fit the memory constraints of the Game Boy. To achieve this, I devised a method to serialize the Trie into a compact binary format that conserves space.

The serialization process transformed each Node into a 32-bit representation, splitting the data into distinct segments: 5 bits for the character, 15 bits for child pointers, 5 bits for child counts, 6 bits for scores, and a single bit for the completion flag. This efficient layout ensured that I could store a wealth of information in a limited space.

Here’s a glimpse of how I structured the serialization:

        val = ((char & 0b11111) << 27) | \
            ((child_ptr & 0b111111111111111) << 12) | \
            ((child_count & 0b11111) << 7) | \
            ((score & 0b111111) << 1) | \
            (complete & 1)

Since this will still require about 24k nodes it cant be stored in a single rom bank. A great way to embrase larger memory requirements on the gameboy is to use memory bank controllers in gbdk. More info here: https://gbdk-2020.github.io/gbdk-2020/docs/api/docs_rombanking_mbcs.html

After successfully generating the C header and source files, I split the data across multiple ROM banks to accommodate the entire 10k dictionary, effectively sidestepping the memory limits of the Game Boy.

Navigating the Path: Traversing the Trie in C

With the Trie encoded in C, the next step was to implement traversal logic that enables real-time predictive text functionality. The traversal involves navigating the Trie based on user input, translating keypresses into the corresponding characters.

The core function utilizes a stack to keep track of the current node and its depth, ensuring efficient exploration of the Trie. By converting user inputs from letters to corresponding number keys (as seen in traditional T9 input), the system can quickly find matching words.

void t9_algorithm(char* val, uint8_t size, T9Results* results) {
    // Logic to find words in the Trie based on input
}

This function not only identifies valid words based on the input sequence but also scores them for relevance, ensuring that the most appropriate suggestions appear first.

Seamless Input: Designing the Keyboard UI and Input System

Now that the backend was functional, it was time to focus on the user interface. Designing the input system for the Game Boy required a balance between accessibility and efficiency. I utilized the built-in background tiles to represent characters visually, allowing users to see their options clearly.

To capture user input, I implemented a system that debounces the buttons, ensuring that multiple buttons are registered at once for diagonals. Here’s a quick overview of the input handling:

// public
uint8_t input_press;
uint8_t input_down;
uint8_t input_up;

// private
uint8_t input_down_buffer;
uint8_t input_prev;
uint8_t input_down_timer = 0;

void update_input(void) {
    input_prev = input_press;
    input_press = joypad();
    input_up = input_prev & ~input_press;

    input_down = 0; // reset down

    // input down without delay
    uint8_t input_down_now = input_press & ~input_prev;

    // handle input down with delay for combos 
    input_down_timer--;

    // add current down to buffer
    if(input_down_now) {
        input_down_timer = INPUT_DOWN_DELAY;
        input_down_buffer |= input_down_now;
    }

    // Commit buffer
    if(input_down_timer == 0) {
        input_down = input_down_buffer;
        input_down_buffer = 0;
    }
}

The Final Word: Conclusions and Future Horizons

Reflecting on this project, I’m proud of the progress made in optimizing typing speed on the Game Boy. The integration of a T9 predictive text system not only enhances user interaction but also opens doors to more complex functionalities. My journey doesn’t end here; I’m currently exploring ways to incorporate internet connectivity into this Game Boy OS, allowing for app integration and dynamic updates.

The knowledge gained through this project is invaluable, and I look forward to sharing more about the ongoing developments. Stay tuned for updates as I push the boundaries of what’s possible on this retro platform!

Repository : https://github.com/cleggacus/gbos
See it working : https://www.youtube.com/shorts/qvXVCzCBPLs

Rust Trait Implementation Wizardry 🧙: Unveiling the Magic of Macro Rules

Liam Clegg — Sun, 21 May 2023 19:49:23 +0000

IMPORTANT: This article will be a continuation of my previous article about rust traits. So go quickly read it first if you need to understand rust traits. The best TRAIT of RUST 🔥 (no pun intended)

Introduction

If you have ever used rust it may seem like you have to rewrite a lot of code due to how the only way you can add repeatable functionality is through composing your structs with traits. Well lucky for you there is this amazing feature called macros.

What is a macro in rust?

Macros can help use write a function that generates code at compile time. Using macros can make you a much faster programmer since you can write a macro that will implement traits for you meaning you don't have to keep doing the tedious task of rewriting your implementation over and over again.

There are 2 main types of macros in rust: declarative and procedural. Declarative macros in rust are usually referred to as macro rules since they are created but typing macro_rules!. On the other hand procedural macros are used for directly accessing the token stream to consume and produce syntax in rust. Procedural macros are used through the proc-macro crate and are not going to be the focus of this article.

For this article we will be using macro rules since they are builtin without having to add any crates and are much simpler to create.

Let's start coding!

For this example we will be continuing from the last article about rust traits. If you wish to follow along you can grab the code from GitHub: Best trait of rust repository

What is a number?

So far we have said that to create a Vec2 for type T it must implement the Add trait. This is so that Vec2 can be also used for addition. Since we need lots more operations we can define a number trait to make things a little easier.

pub trait Number: 
    Clone +
    Copy +
    Sized + 
    Add<Output = Self> + 
    Sub<Output = Self> + 
    Div<Output = Self> + 
    Mul<Output = Self> + 
    AddAssign + 
    SubAssign + 
    DivAssign + 
    MulAssign {}

This trait might not have any direct functionality but it does mean when ever we want to say that a generic has all the other necessary trait we just have to say it implements number.

This now means that we will need to implement number for all the number types. The first thought might be to write it out like this.

impl Number for f32 {}
impl Number for f64 {}
impl Number for u32 {}
impl Number for u64 {}
impl Number for u128 {}
impl Number for i32 {}
impl Number for i64 {}
impl Number for i128 {}

Now this isn't to bad and it might be the way you would prefer to write your code since it is more verbose. But for the sake of this article we will make this less verbose through macro rules.

First we think of how we wish the macro rule to look. To make the code super simple we can have a macro rule named impl_number with a list of types that will implement number. It will look something like this.

impl_number!(usize, f32, f64, u32, u64, u128, i32, i64, i128);

To create a macro we start with macro_rules! followed by the name of the macro impl_number.

macro_rules! impl_number {
    // code goes here
}

We now need need to actually create a the code to generate the line impl Number for type_name_here {}.

To do this we create a function that takes the designator ty (which is used for types). A designator is basically just the type of thing you are passing to the macro. The matcher will be written as $t:ty where $t is the argument name and ty is the designator type.

We can then simply write in the function the code we wish to generate. So in this case impl Number for $t {}. To impliment a single type for a trait would look like this.

macro_rules! impl_number {
    ($t:ty) => {
        impl Number for $t {}
    };
}

So this is great and all but this only implements one type. To allow a list of arguments to be passed we need surround the matcher with $(...),+. If we wish to repeat the generated code for each argument we can surround the code with $(...)*. All together this will look like the following.

macro_rules! impl_number {
    ($($t:ty),+) => {
        $(impl Number for $t {})*
    };
}

We can now below this write the following to actually implement the types.

impl_number!(usize, f32, f64, u32, u64, u128, i32, i64, i128);

Now we can rewrite the Vec2 struct from this:


pub struct Vec2<T> 
where
    T: Add<Output = T> + Copy + Clone
{
    pub x: T,
    pub y: T
}

To this:

#[derive(Debug, Copy, Clone)]
pub struct Vec2<T: Number>  {
    pub x: T,
    pub y: T
}

Operations

There is mainly 2 operations we wish to implement for the Vec2 struct. The first is operators that create a new value and then there's operators that also assign the value. In the previous article we looked at how the implement the Add trait and used the following code:

impl<T> Add for Vec2<T> 
where
    T: Add<Output = T> + Copy + Clone
{
    type Output = Vec2<T>;

    fn add(self, rhs: Self) -> Self::Output {
        Vec2 {
            x: self.x + rhs.x, 
            y: self.y + rhs.y
        }
    }
}

If we look at this implementation block there are only a couple things that change between operators. The trait name changes and the function name changes. Although the operator symbol also changes we can just call the method directly instead.

To implement this as a macro we will use the name impl_vec2_op. This will take 2 designators: an identifier for the trait and an identifier for the method name. An identifier is represented by the keyword ident. We can then replace the trait name with $trait and the method name with $func. The completed macro rule looks like the following.

macro_rules! impl_vec2_op {
    ($trait:ident, $func:ident) => {
        impl<T: Number> $trait for Vec2<T> {
            type Output = Self;

            fn $func(self, rhs: Self) -> Self::Output {
                Vec2 {
                    x: self.x.$func(rhs.x),
                    y: self.y.$func(rhs.y)
                }

            }
        }
    };
}

We then run the macro with add, sub, div and mul with the following lines.

impl_vec2_op!(Add, add);
impl_vec2_op!(Sub, sub);
impl_vec2_op!(Div, div);
impl_vec2_op!(Mul, mul);

To show the benefits to this macro based approach lets say we now wish to allow adding a number T to a vector Vec2<T>. We can easily add the implementation block to the macro so that it is implemented for all the operations.

impl<T:Number> $trait<T> for Vec2<T> {
    type Output = Self;

    fn $func(self, rhs: T) -> Self::Output {
        Vec2 {
            x: self.x.$func(rhs),
            y: self.y.$func(rhs)
        }
    }
}

Altogether the macro would look like this:

macro_rules! impl_vec2_op {
    ($trait:ident, $func:ident) => {
        impl<T: Number> $trait for Vec2<T> {
            type Output = Self;

            fn $func(self, rhs: Self) -> Self::Output {
                Vec2 {
                    x: self.x.$func(rhs.x),
                    y: self.y.$func(rhs.y)
                }
            }
        }

        impl<T:Number> $trait<T> for Vec2<T> {
            type Output = Self;

            fn $func(self, rhs: T) -> Self::Output {
                Vec2 {
                    x: self.x.$func(rhs),
                    y: self.y.$func(rhs)
                }
            }
        }
    };
}

We can now similarly do this for the assignment operators with the following macro rule.

macro_rules! impl_vec2_op_assign {
    ($trait:ident, $func:ident) => {        
        impl<T: Number> $trait for Vec2<T> {
            fn $func(&mut self, rhs: Self) {
                self.x.$func(rhs.x);
                self.y.$func(rhs.y);
            }
        }

        impl<T: Number> $trait<T> for Vec2<T> {
            fn $func(&mut self, rhs: T) {
                self.x.$func(rhs);
                self.y.$func(rhs);
            }
        }
    };
}

impl_vec2_op_assign!(AddAssign, add_assign);
impl_vec2_op_assign!(SubAssign, sub_assign);
impl_vec2_op_assign!(DivAssign, div_assign);
impl_vec2_op_assign!(MulAssign, mul_assign);

Finally we can update our ToVec2 trait. For this we will instead use the From trait since it is included in the standard library. Since we have a generic we do not need to create a macro rule for this.

impl<T: Number> From<T> for Vec2<T> {
    fn from(val: T) -> Self {
        Vec2 {
            x: val,
            y: val,
        }
    }
}

Lets quickly write a test

We first need to implement partial equals for the Vec2 struct. This is simple. We just need to add it to number and then derive it in Vec2.

pub trait Number: 
    PartialEq +
    ...

#[derive(Debug, Copy, Clone, PartialEq)]
pub struct Vec2<T: Number>  {
    ...

Note: I removed the main.rs file from the previous article

We can then write our test in lib.rs as follows:

pub mod vec2;

#[cfg(test)]
mod tests {
    use crate::vec2::Vec2;

    #[test]
    fn it_works() {
        // 5, 5
        let v1: Vec2<i32> = 5.into();

        // 1, 2
        let v2 = Vec2 {
            x: 1,
            y: 2
        };

        // 6, 7
        let mut v3 = v1 + v2;

        // 12, 14
        v3 *= Vec2::from(2);

        assert_eq!(v3, Vec2 {
            x: 12,
            y: 14
        });
    }
}

We can now run the test with:

cargo test

And we get the following output.

IT WORKS!!!

Find the full code here: Trait Implementation Wizardry

Challenge

Try and write some macros for casting between numbers using the from trait.

Conclusion

We have explored how to fix the issue with repeating trait implementation blocks by using macro rules and how we can practically do this with the Vec2 example from the previous article. If you have any questions leave a comment and it would be much appreciated if you drop a like if you enjoyed this article, thanks!

The best TRAIT of RUST 🔥 (no pun intended)

Liam Clegg — Fri, 05 May 2023 04:30:44 +0000

Introduction

So, your friend can't stop about how they use Rust. Perhaps they've mentioned how it's safe, has great memory management or how its BLAZINGLY fast. Although this is clearly true, there is another great reason to use rust: its use of traits.

Never heard of traits? well its your lucky day.

What is a trait?

Do you remember when you first learnt inheritance and it seamed like this amazing idea. So you create an animal class that allows for a noise method and an eat method. You then you create a cat and a dog who have these methods. You then want a robot who speaks but doesn't eat. Well now you need a speaker class that the animal class extends and the robot class extends. Suddenly, when you realize that the cat and the robot both need to catch mice, you find yourself struggling to figure out what to do. Everything you were promised about inheritance seems like a lie.

Fortunately, there is another approach to this problem called composition. Instead of a cat being an animal, a cat is an entity composed of the traits speaker, eater, and mouse hunter. The robot is composed of the speaker and mouse hunter traits. With composition, you can create more flexible and reusable code that adapts to different contexts. This is why traits are super useful in rust.

Now, you are probably thinking that this already exists in other languages like java and c#. But there are a few nifty tricks that traits have in rust that do not exist in these other languages. We will see them a bit later.

The Vector Example

An example that I personally think shows off traits the most is vectors. The math kind not the array kind.

All code examples can be found on Github: rust-traits-example

Creating a Vec2 Struct

Lets first define a Vec2 struct with a generic type for the x and y attributes.

struct Vec2<T> {
    x: T,
    y: T
}

Printing

Now in our main lets create a Vec2 and print it.

fn main() {
    let v1 = Vec2 {
        x: 1,
        y: 2,
    };

    println!("{}", v1);
}

You will quickly realize this doesn't work when the compiler throws the error doesn't implement 'std::fmt::Display'. This happens because the Display trait must be implemented for the type that you are printing.
A quick solution to this will be to print using the Debug trait instead. This is because unlike the Display trait you can derive the Debug trait. This essentially a macro (or code generated at compile time) that will automatically implement the trait for you. This can be done by adding #[derive(Debug, Copy, Clone)] above the struct. Note: "{:?}" is used for debug in the print macro.

#[derive(Debug)]
struct Vec2<T> {
    x: T,
    y: T
}

fn main() {
    let v1 = Vec2 {
        x: 1,
        y: 2,
    };

    println!("{:?}", v1);
}

Implementing traits for existing types

So now lets say we want to be able to convert an i32 (32 bit integer) to a Vec2. One way we can do this is by creating a ToVec2 trait that must derive a to_vec2 function.

trait ToVec2<T> {
    fn to_vec2(&self) -> Vec2<T>;
}

impl ToVec2<i32> for i32 {
    fn to_vec2(&self) -> Vec2<i32> {
        Vec2 { 
            x: *self,
            y: *self 
        }
    }
}

This now means we can call the method to_vec2 on any variable with the i32 type. This is something that interfaces cannot do in other languages and why traits are so powerful in rust.
We can now modify the main function to show this working in action.

fn main() {
    let v1 = Vec2 {
        x: 1,
        y: 2,
    };

    let v2 = 8.to_vec2();

    println!("{:?}, {:?}", v1, v2);
}

Operation overloading

Another use case for traits is operation overloading. This is where you have a struct or class and wish to allow the user to use an operator such as '+' to add the two values together.
Lets now implement the Add trait for Vec2. To do this we will first need to insure that the generic used for x and y also have this trait so they can be added to the other vectors x and y values. There are 2 types of syntax we can use for this.
The first way is to add a bound in the angle brackets. This is good for when your adding one or two traits.

use std::ops::Add;

#[derive(Debug)]
struct Vec2<T: Add> {
    x: T,
    y: T
}

But lets say we wish to have multiple traits. In this case lets add the Copy and Clone traits too. We can now use the where keyword as follows.

use std::ops::Add;

#[derive(Debug)]
struct Vec2<T> 
where
    T: Add
       + Clone
       + Copy
{
    x: T,
    y: T
}

We need to also make sure that these bounds exist on the ToVec2 trait since it also uses this generic.

trait ToVec2<T>
where
    T: Add
       + Clone
       + Copy
{
    fn to_vec2(&self) -> Vec2<T>;
}

Now we need to implement Add for Vec2. To do this we will need to define the output type of type Vec2 and also we need to make sure the Add bound for T is Add since The output of the addition must also have the traits required for a Vec2.

impl<T> Add for Vec2<T>
where
    T: Add<Output = T>
       + Clone
       + Copy
{
    type Output = Vec2<T>;

    fn add(self, rhs: Self) -> Self::Output {
        Vec2 {
            x: self.x + rhs.x, 
            y: self.y + rhs.y
        }
    }
}

Before we test this me need to make sure that Vec2 also derives the Copy and Clone to prevent issues related to borrowing.

#[derive(Debug, Clone, Copy)]
struct Vec2<T>

Finally we can test if the addition works by updating our main function.

fn main() {
    let v1 = Vec2 {
        x: 1,
        y: 2,
    };

    let v2 = 8.to_vec2();

    let v3 = v1 + v2;

    println!("{:?} + {:?} = {:?}", v1, v2, v3);
}

IT WORKS!!!

https://github.com/cleggacus/rust-traits-example/tree/1_best_trait_of_rust

Challenge

Try and implement more operations for this struct and implement the ToVec2 trait for more types. If you would like to do your own further reading maybe try to replace the ToVec2 for the Into and From traits.

Conclusion

We've explored the issues with inheritance and how trait based composition can help this by using rust. We've looked at how traits are derived, used for operation overloading and implemented for already existing types. Hopefully this is a compelling reason to use fast apart from its BLAZINGLY FAST performance.

Thanks for reading!

P.S. If you share, comment and like this post I will show how we can one up this Vec2 struct with macros to do the work for us.

Tiling Window Managers Are The Reason I Use Linux

Liam Clegg — Wed, 26 Apr 2023 12:51:14 +0000

My Situation

For the past few years, I've been switching back and forth between Windows and Linux. However, every time I try to switch to Windows, I end up going back to Linux because of one specific feature - tiling window managers. Unlike the commonly cited features of Linux such as being open source, privacy or security, tiling window managers are what really draw me in.

The Problem With Windows

Do you consider yourself a speed demon when it comes to navigating through windows on your computer? If so, then the trusty old "alt-tab" shortcut must be a go to for you. But let's face it, when you have multiple windows open, this method can quickly turn into a nightmare. While it works wonders when you only have a few windows open, you can quickly find yourself with dozens of windows open desperately spamming the tab key, only to accidentally click on the wrong window. It's a frustrating and all too common experience for people using windows, mac and even Linux users who use popular desktop environments such as plasma and gnome.

The solution

So now you understand the problem whats the solution. Well luckily of you there's this wonderful thing called tiling window managers. A tiling window manager is piece of software which manages your windows by aligning them to a tiling layout. With this set up you can now manipulate your desktop with shortcuts allowing you to move windows around, scale windows and even organize them into groups.

Now your probably asking how this solves the issue since you still are going to have to switch between a lot of windows and not all of them can be open at once. Well this is where the concept of multiple desktops come in. A virtual desktop is essentially a group of windows that are in a specific layout. You can usually quickly switch between them using a shortcut involving the desktops number. In the case of i3 and sway this shortcut is "win + number". This at first may seem confusing since you don't know which number go to which desktop. The way you tend to manage this is but only ever putting certain things in certain desktops.

For example I personally use desktop 1 for a general terminal, desktop 2 for vim of some other IDE, 3 for web browser and so on.

Now I here what your saying "virtual desktops already exist in windows". But if you've ever tried using virtual desktops you have found the same issue with alt tab. You have to spam "win shift arrow" until you get to the desired desktop. The benefit to having a numbered system for your desktops is once your used to it you don't have to about it. Your monkey brain will just go directly to the correct desktop without even thinking about it.

The drawbacks

Personally I do not have any drawbacks to tiling window managers apart from the time you have to put into setting it up and learning them. One minor drawback might be that it looks bad initially but this can be fixed with configuration which can be fun if you are like me. For example this is what my current set up looks like.

My config: https://github.com/cleggacus/sway-ricey-boi

Most of my issues in the past have come from things sometimes breaking and not working perfectly in Linux. But every time I got back to Linux I have found my self getting better and having less issues and I'm finally at a point where I don't think ill need to go back to windows.

So what now?

So now you know the benefits to tiling window managers you may be thinking to your self that you would like to try it but don't know where to start. I would likely recommend i3 as one that I have used in the past but I have heard good things when it comes to bspwm and awesome. I personally use sway but i3 will probably be easier to set up and trouble shoot since its older and more widely used.

How To Make A Next JS Blog With Markdown And TypeScript

Liam Clegg — Sun, 21 Aug 2022 08:49:00 +0000

This tutorial will show you how to make a Next js blog with markdown and typescript. Next js is a React framework that will allow you to SSR (server side render), boosting its SEO performance. SEO optimization will allow you to increase your social presence on Google search. Whether you’re a student, a freelancer or professional this is an essential skill to have when becoming a professional web developer.

Setup

The easiest way to start the project is with the create next app typescript boilerplate.

# with yarn
yarn create next-app blog --typescript

# with npm
npx create-next-app blog --ts

After this, you will need to install all the relevant dependencies.

gray-matter is used to read the metadata such as the thumbnail, description, and title. react-markdown is used to render out the markdown into HTML. react-syntax-highlighter is used to add syntax highlighting to the code blocks within the rendered markdown.

# with yarn
yarn add gray-matter react-markdown react-syntax-highlighter
yarn add @types/react-syntax-highlighter --dev

# with npm
npm install gray-matter react-markdown react-syntax-highlighter
npm install  @types/react-syntax-highlighter --save-dev

remove pages/api directory since it is not needed

Create Articles

Create a directory named uploads with some template markdown files. Metadata is surrounded by 3 dashes and has a title, description, and thumbnail. An example of an article is below. The name of the file will be the URL slug.

---
title: "Eget Duis Sem Tincidunt Ac Ullamcorper Et Turpis Magna Viverra"
description: "risus eu lectus a consectetur aliquam nullam enim tellus urna nunc sagittis aenean aliquam ullamcorper consectetur dictumst sit, placerat eget lobortis eget elit nibh blandit scelerisque consectetur condimentum diam tempor. nisl erat semper gravida tempor aliquam suscipit a viverra molestie sit porta cras ultricies, fermentum habitasse sit semper cum eu eget lacus purus viverra cursus porttitor nisi nisl."
thumbnail: https://blogthing-strapi.cleggacus.com/uploads/0_d65573c0b9.jpg
---
# In Eu Sapien Tellus Id
## Ullamcorper Elit Semper Ultricies Morbi
sit at blandit cras id eu congue et platea massa lectus netus vulputate suspendisse sed, risus habitasse at purus nibh viverra elementum viverra arcu id vulputate vel. ipsum tincidunt lorem habitant dis nulla consectetur tincidunt iaculis adipiscing erat enim, ultrices etiam mollis volutpat est vestibulum aliquam lorem elit natoque metus dui est elit. mollis sit tincidunt mauris porttitor pellentesque at nisl pulvinar tortor egestas habitant hac, metus blandit scelerisque in aliquet tellus enim viverra sed eu neque placerat lobortis a. laoreet tempus posuere magna amet nec eget vitae pretium enim magnis, cras sem eget amet id risus pellentesque auctor quis nunc tincidunt tortor massa nisl velit tortor. a volutpat malesuada nisi habitasse id volutpat nibh volutpat suspendisse nunc justo elementum ac nec, elementum pulvinar enim sociis nunc eleifend malesuada platea nunc posuere aliquet ipsum.
\`\`\`ts
function someFunc(thing: string){
    const thing2 = thing[0];
    return thing2;
}
\`\`\`

Interfaces

Before adding code it is best to create an interfaces directory and add some interfaces so we know the structure of the data that is fetched. These interfaces will make use that the metadata and info of an article post follow a set structure.

interface ArticleMeta {
    title: string;
    slug: string;
    description: string;
    thumbnail: string;
}

interface ArticleInfo {
    meta: ArticleMeta;
    content: string;
}

export type {
    ArticleMeta,
    ArticleInfo
}

Components

We can now create a components directory that will store all components used in the project. This will include a card component and a markdown component which will hold our code for rendering our markdown with syntax highlighting.

Card Component

The card component will take in the property article which will be of type ArticleMeta. This is declared in the interface IProps.

components/card.tsx

import Link from "next/link";
import { FunctionComponent } from "react";
import { ArticleMeta } from "../interfaces/article";
import styles from "../styles/card.module.css";

interface IProps {
    article: ArticleMeta;
}

const Card: FunctionComponent<IProps> = ({ article }) => {
    return <Link href={`/article/${article.slug}`}>
        <div className={styles.card}>
            <img src={article.thumbnail} />

            <div className={styles.info}>
                <h1>{article.title}</h1>
                <p>{article.description}</p>
            </div>
        </div>
    </Link>
}

export default Card;

The card is styled so that it can be in a grid made with CSS flex.

styles/card.module.css

.card{
    cursor: pointer;
    display: flex;
    flex-direction: column;
    overflow: hidden;
    width: 300px;
    height: 400px;
    margin: 20px;
    background-color: #fff;
    box-shadow: 0 4px 8px 0 #0001, 0 6px 20px 0 #0001; 
    border-radius: 10px;
    transition: all 0.3s;
}

.card:hover{
    width: 320px;
    height: 420px;
    margin: 10px;
}

.card:hover .info {
    padding: 20px 30px;
}

.card img{
    width: 100%;
    flex: 1;
}

.card .info{
    width: 100%;
    height: 200px;
    padding: 20px;
    transition: all 0.3s;
}

.card .info h1,
.card .info p {
    color: #555;
    display: -webkit-box;
    -webkit-box-orient: vertical;
    overflow: hidden;
}

.card .info h1{
    margin: 0;
    font-size: 1.3em;
    -webkit-line-clamp: 2;
}

.card .info p{
    margin: 10px 0 0 0;
    -webkit-line-clamp: 4;
}

Markdown Component

The markdown component will take the prop content. Content is a string that holds the markdown code to be rendered.

import ReactMarkdown from 'react-markdown';
import { NormalComponents, SpecialComponents } from 'react-markdown/src/ast-to-react';
import { materialLight } from 'react-syntax-highlighter/dist/cjs/styles/prism';
import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter';
import { FunctionComponent } from 'react';

interface IProps {
    content: string;
}

const Markdown: FunctionComponent<IProps> = ({content}) => {
    const components: Partial<NormalComponents & SpecialComponents> = {
        code({node, inline, className, children, ...props}) {
            const match = /language-(\w+)/.exec(className || '');

            return (!inline && match) ? (
                <SyntaxHighlighter style={materialLight} PreTag="div" language={match[1]} children={String(children).replace(/\n$/, '')} {...props} />
            ) : (
                <code className={className ? className : ""} {...props}>
                    {children}
                </code>
            )
        }
    }

    return <div className="markdown-body">
        <ReactMarkdown components={components} children={content} />
    </div>
}

export default Markdown;

To style the markdown it is surrounded by a div tag with the class name markdown-body. Copy the CSS file from https://github.com/cleggacus/next-blog-medium-tutorial/blob/master/styles/markdown.css and save it as styles/markdown.css

Add the line below to your _app.tsx file to import the CSS file.

import '../styles/markdown.css'

Pages

There are 2 pages that are needed: an index page and an article page. The index page will show all the articles in a grid and the article page will show all the contents of the article.

Index Page

There are 2 pages that are needed: an index page and an article page.

The index page will show all the articles in a grid and the article page will show all the contents of the article.

import styles from '../styles/Home.module.css'
import Card from '../component/card'
import fs from 'fs'
import matter from 'gray-matter'
import { ArticleMeta } from '../interfaces/article'
import { FunctionComponent } from 'react'

interface IProps {
    articles: ArticleMeta[];
}

const Home: FunctionComponent<IProps> = ({ articles }) => {
    return (
        <div className={styles.container}>
        {
            articles.map((article, i) => (
                <Card key={i} article={article} />
            ))
        }
        </div>
    )
}

Then we can fetch the articles with getStaticProps. Get static props is an async function that will statically generate the page with the fetched data returned from the function.

fs.readdirSync(“uploads”) is used to get an array of all the files in the uploads directory.

const files = fs.readdirSync("uploads");

The files are then read and mapped to an array of ArticleMeta. The files are read using readFileSync and casting it to a string.

const data = fs.readFileSync(`uploads/${file}`).toString();

matter(string).data will return the metadata of the markdown. The slug is then generated by splitting at the ‘.’ char and getting the string at index 0. This will remove the ‘.md’ extension of the filename

return {
    ...matter(data).data,
    slug: file.split('.')[0]
}

The full code of getStaticProps is below.

export async function getStaticProps() {
    const files = fs.readdirSync("uploads");

    let articles = files.map(file => {
        const data = fs
            .readFileSync(`uploads/${file}`)
            .toString();

        return {
            ...matter(data).data,
            slug: file.split('.')[0]
        };
    });

    return {
        props: {
            articles: articles
        }
    };
}

The final index.tsx file is shown in the code below

import styles from '../styles/Home.module.css'
import Card from '../component/card'
import fs from 'fs'
import matter from 'gray-matter'
import { ArticleMeta } from '../interfaces/article'
import { FunctionComponent } from 'react'

interface IProps {
    articles: ArticleMeta[];
}

const Home: FunctionComponent<IProps> = ({ articles }) => {
    return (
        <div className={styles.container}>
        {
            articles.map((article, i) => (
                <Card key={i} article={article} />
            ))
        }
        </div>
    )
}

export async function getStaticProps() {
    const files = fs.readdirSync("uploads");

    let articles = files.map(file => {
        const data = fs
            .readFileSync(`uploads/${file}`)
            .toString();

        return {
            ...matter(data).data,
            slug: file.split('.')[0]
        };
    });

    return {
        props: {
            articles: articles
        }
    };
}

export default Home;

styles/Home.module.css

.container{
    display: flex;
    justify-content: center;
    flex-wrap: wrap;
    min-height: 100vh;
    width: 100%;
    padding: 20px;
}

Article Page

The article file is at the location ‘pages/article/[slug].tsx’

The article component takes an article prop of type ArticleInfo to create the article page.

import { FunctionComponent } from "react";
import fs from 'fs';
import matter from "gray-matter";
import styles from '../../styles/article.module.css';
import { ArticleInfo } from "../../interfaces/article";
import Markdown from "../../component/markdown";

interface IProps {
    article: ArticleInfo;
}

const Article: FunctionComponent<IProps> = ({ article }) => {
    return <div className={styles.article}>
        <div className={styles.thumbnail}>
            <img src={article.meta.thumbnail} />

            <div className={styles.title}>
                <h1>{article.meta.title}</h1>
            </div>
        </div>

        <div className={styles.content}>
            <Markdown content={article.content} />
        </div>
    </div>
}

The square brackets in the file name are used for a dynamic route. To statically generate the article pages the getStaticPaths function is used. getStaticProps will return an array of all the routes that have a page.

Each file in the uploads directory is mapped to an array of routes. The routes are the slugs of the articles. The slug is generated the same way it was on the home page.

export async function getStaticPaths() {
    const files = fs.readdirSync("uploads");
    const paths = files.map(file => ({
        params: {
            slug: file.split('.')[0]
        }
    }))

    return {
        paths,
        fallback: false,
    }
}

export default Article;

After the paths are generated each page is rendered. The slug is taken in through the ctx parameter.

const {slug} = ctx.params;

The filename is found with the slug by adding the ‘.md’ extension back on the end of the slug. The info in the file is then parsed by using gray matter.

matter(string).data will return the metadata of the Markdown.

matter(string).content will return the body of the Markdown.

The data and content are added to an object called article which is of type ArticleInfo.

export async function getStaticProps({ ...ctx }) {
    const { slug } = ctx.params;

    const content = fs
        .readFileSync(`uploads/${slug}.md`)
        .toString();

    const info = matter(content);

    const article = {
        meta: {
            ...info.data,
            slug
        },
        content: info.content
    }

    return {
        props: {
            article: article
        }
    }
}

The complete code for pages/article/[slug].tsx is below.

import { FunctionComponent } from "react";
import fs from 'fs';
import matter from "gray-matter";
import styles from '../../styles/article.module.css';
import { ArticleInfo } from "../../interfaces/article";
import Markdown from "../../component/markdown";

interface IProps {
    article: ArticleInfo;
}

const Article: FunctionComponent<IProps> = ({ article }) => {
    return <div className={styles.article}>
        <div className={styles.thumbnail}>
            <img src={article.meta.thumbnail} />

            <div className={styles.title}>
                <h1>{article.meta.title}</h1>
            </div>
        </div>

        <div className={styles.content}>
            <Markdown content={article.content} />
        </div>
    </div>
}

export async function getStaticProps({ ...ctx }) {
    const { slug } = ctx.params;

    const content = fs
        .readFileSync(`uploads/${slug}.md`)
        .toString();

    const info = matter(content);

    const article = {
        meta: {
            ...info.data,
            slug
        },
        content: info.content
    }

    return {
        props: {
            article: article
        }
    }
}

export async function getStaticPaths() {
    const files = fs.readdirSync("uploads");
    const paths = files.map(file => ({
        params: {
            slug: file.split('.')[0]
        }
    }))

    return {
        paths,
        fallback: false,
    }
}

export default Article;

The CSS for the article page is at styles/aricle.css

.article{
    display: flex;
    flex-direction: column;
    align-items: center;
    width: 100%;
    min-height: 100vh;
    padding-bottom: 100px;
}

.thumbnail{
    position: relative;
    width: 100%;
    height: 700px;
}

.thumbnail .title{
    position: absolute;
    padding-bottom: 100px;
    display: flex;
    justify-content: center;
    align-items: center;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}

.thumbnail .title h1{
    text-align: center;
    width: 70%;
    color: #fff;
    font-size: 3em;
}

.thumbnail img{
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
    filter: brightness(0.5);
}

.content{
    z-index: 1;
    margin-top: -100px;
    padding: 50px;
    border-radius: 10px;
    width: 70%;
    background-color: #fff;
    box-shadow: 0 4px 8px 0 #0001, 0 6px 20px 0 #0001; 
}

In conclusion, next js can easily be used as a way to server-side render react code. We have used both getStaticProps and getStaticPaths to general static pages with the static and dynamic routes.

Get the full source code for this project at https://github.com/cleggacus/next-blog-medium-tutorial