DEV Community: Luke Nguyen

Release 0.4 - Part 3

Luke Nguyen — Fri, 10 Dec 2021 20:54:56 +0000

Introduction

With both pull requests submitted and one of them being merged recently, we are approaching the final chapters of this journey. This blog, the last one of the release 0.4 trilogy, will be about the process of participating in code reviews for the pull requests.

The issues

1. #issue-2416

While the initial release looks good, some places need improvements:

Addressing the problem where the build status get refreshed every 5 seconds
Rebasing and moving the code for the build header to a new location to accommodate for the newly added Handlebars feature

For the first problem, the culprit was the 2 toggleAttribute calls inside renderBuildInfo():

resMsg.toggleAttribute('hidden');
buildHeaderInfo.toggleAttribute('hidden');

As such, I had to find a workaround to replicate the behaviour, and using "innerHTML" seems to be the best option:

buildHeaderTitle.innerHTML = '';

For the second problem, I reached out to the classmate who added the templating engine and was able to get him to explain the changes he made. With all of the questions clarified, I referred to the Handlebars documentation and slowly migrated the code to its new location. Once done, I also performed a small test to ensure that the two functions that fetch and render the data were called.

2. #issue-107

As for this pull request, the code review went much more smoothly, with me having to only make minor changes to ensure that it would not cause any errors when built.

Conclusion

And with that, I'm almost done with the release! By the time this blog is up, I still have a little bit more work to do, mostly refining and optimizing #issue-2416 to get it ready for PR. The journey until now was not easy, and I was a bit disappointed that I couldn't contribute as much as I wanted to. Compared to my performance in previous releases, I would give myself only a 6/10, as I felt like I could do more than just taking only two issues. But with that said, I'm still proud of what I have done.

Release 0.4 - Part 2

Luke Nguyen — Fri, 10 Dec 2021 12:33:37 +0000

Introduction

Continuing with my release 0.4, I started putting my plan for the two selected issues into action. After talking with the project maintainers and noting down almost everything I needed to know, I was confident that I could get both pull requests up for review within the week. Sadly, things did not go as planned.

Working on the issues

1. #issue-2416

At first, I intended to reuse the existing table layout and only made tiny modifications. However, I soon realized that this approach only made everything more difficult. By duplicating the code, not only did I make the already bulky HTML even harder to read, but it also made naming classes, IDs, and performing DOM manipulation to render the data more challenging. After several days of just writing and deleting the same code, I decided to go back to the drawing board.

Initial design

To make the final product matches the provided example, I had to choose between flexbox and grids. Both of them will get the job done, but to my experience, I find that grid is much simpler to use. After hours of sketching out the design in my notebook, it was time to write the actual code. I started working my way slowly through each section of the layout, adding minor adjustments and constantly going back and forth between the Bootstrap documentation to ensure the result looked good on the web.

My ugly sketch of the new layout

Final result

Another roadblock I had while working on this issue was figuring out how to fetch the data and render them to the UI. I initially thought I had to make an API call and process the data, but one of the maintainers mentioned that doing so was unnecessary. Thus, I had to play around with the return values inside the function responsible for fetching the data. After hours of logging different variables, objects, messages, and a couple of calls with one of the maintainers, I managed to get everything worked and combine it with the design I made earlier.

2. #issue-107

Surprisingly, I hadn't had as much trouble working on this as the previous one. As a lot of the work was similar to one of my labs about continuous integration, I was able to use it as a reference and quickly get my pull request up for review.

Conclusion

It has been a rough week, but I managed to get both the issues up and ready for review. By the time this blog is up, #issue-107 has been merged successfully, while #issue-2416 was on its final stage of reviewing. I'll be waiting for feedback and making any modifications where necessary.

Release 0.4 - Part 1

Luke Nguyen — Tue, 30 Nov 2021 03:09:28 +0000

Introduction

Finally, we managed to reach the end of my first open-source course. And, what better way to end it than challenging myself to work on something even bigger and more impactful compared to my previous releases?

This blog will be the first of my 3-part journey tackling the final release: from planning the approach to the assigned issues and working on the code to finally submitting the PR(s) and making adjustments based on others' feedback.

The search 🔎

First things first, we need to get ourselves some issues.

I decided to look inside Telescope and the IPC144 curriculum repo and after a while, managed to find myself 2 issues:

Planning 📝

1. #issue-2416

After talking with the project maintainers, I managed to write down a few things about my approach:

Fetching the builds' (previous, current, next) detail from the Telescope API
Extracting the following info from the fetched result:

{
  * The git SHA that is/was built
  * Who pushed the code (i.e., pusher)
  * Who wrote the code (i.e., sender/author)
  * A link to the compare branch to see what changed
  * When the build started (startedDate)
  * When the build stopped (stoppedDate)
  * What the result code of the build was
}

Rendering the data to a UI element to display it in both the dashboard and the build log

For the place that hosts the logic to fetch and extract data from the API, I was suggested to create a new file in https://github.com/Seneca-CDOT/telescope/tree/master/src/api/status/public/js/build-log

For the UI element, I planned on basing my design on GitHub's per one of the maintainers suggestion:

Since the project uses Bootstrap, I could refer to their documentation to create a card component and customize it to match the example as closely as I can.

2. #issue-107

Since the task is to add more scripts to improve the current CI workflow, I could refer to a blog I made about GitHub Actions and start from there.

Publishing a project to npm

Luke Nguyen — Sat, 27 Nov 2021 07:45:07 +0000

Introduction 📖

For the past three months, I have been working on my static site generator, adding features and fixing bugs as the project grows. With the recent implementation of static analysis tooling, test suites, and continuous integration, I thought the project was finally ready for public use.

Preparing for release 🛠

1. Making the project callable by its name

To call the project directly, we have to map the entry file to its executable name, which we can do by adding the main and bin value to package.json:

{
  "main": "src/index.js",
  "bin": {
    "mini-cli-ssg": "src/index.js"
  },
}

Inside index.js, we specifiy the environment of the executable by adding the following:

#!/usr/bin/env node

After that, we can register the binary (the bin value) globally by using npm link.

2. Testing the project locally

With npm link, we can now test our project locally on our machine before actually publishing it. Start by creating a temporary directory for testing anywhere on your machine (I recommend putting it on Desktop as it is easier to see). Then, inside the newly created directory, install the project using the following:

npm link mini-cli-ssg

After that, we can play around with the CLI by calling it by its name, passing in different arguments to ensure that all features are working.

3. Adding information to `package.json`

With the code tested and ready for publishing, it is time to prepare the package.json. So far, we already have the basic information covered, like the project name, description, author, etc. However, it is nice to include in more detail such as the project homepage or GitHub repository. We can do so by adding the following values to package.json:

{
  "homepage": "<your GitHub repo/site here>",
  "repository": {
      "type": "git",
      "url": "git+<your GitHub repo here>"
  },
}

Additionally, we also need to ensure that the version number follows the semantic versioning rules. You can check out the full description of it here, or read the shortened version in the npm docs.

Releasing to `npm` 💾

Here are the steps needed to publish the package:

Create an account on npmjs.com
Run the npm login command and input your information
Run the npm publish command which will automatically publish it

Receiving users' feedback

With the package published, I reached out to some of my friends via Discord, asking them to test my code using the installation and usage instructions included in the docs. To my surprise, there were actually some issues that managed to slip through while I was testing it locally:

After calling my friend and watching him run my package, I realized that I did not handle the file path properly. My classmate Duke also had a blog post about a problem similar to this, so I will leave the explanation to him. But in short, I had to change the path names leading to each of the dist and assets into absolute paths using path.resolve().

Conclusion

I can't believe I finally published my first ever package to npm. The experience was terrifying at first, but having someone to view and test your code gives you so many opportunities to learn from it. Additionally, it was satisfying seeing others were able to run your project successfully on their machines.

Adding Continuous Integration with GitHub Actions 🛠

Luke Nguyen — Sat, 20 Nov 2021 07:23:33 +0000

Introduction

With static analysis tooling and unit tests added to the project, it is time to increase the complexity of my project. At the moment, I have written several tests to check on the different functionalities of my program. However, they had to be manually run by executing "npm run test" in the terminal, which will be very tedious if there are a lot of files to test. Additionally, we also need to consider human errors, as there is no way to guarantee that all contributors remember to run the test before committing their code.

Choosing a CI

With this in mind, it is to introduce continuous integration (or CI, for short). It allows us to set up a workflow that listens to every time someone introduces new changes, builds the code, and automatically runs tests against it.

While we have many CI services, such as Azure DevOps, Evergreen, or Jenkins, I'll choose GitHub Actions for this task.

Setting up the CI

There are different options to set up GitHub Actions. You can either choose to do it manually or choose from numerous templates. My project, MINI, works just fine with the Node.js template:

# Title of the workflow
name: Node.js CI

# Trigger this workflow on push and new PR
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# jobs to run inside this workflows
jobs:
  build:
    # choose a platform to run on
    runs-on: ubuntu-latest

    # options
    strategy:
      matrix:
        node-version: [14.x, 16.x]

    steps:
      # use a preset step to checkout the code 
      - uses: actions/checkout@v2
      # use a preset step to setup Node environment
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        # preset options
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      # command to run
      - run: npm ci
      - run: npm test

After setting up GitHub Actions, I made two pull requests to check if it worked as intended: One containing an intentional error and the other with the same error fixed.

Writing test for others

After ensuring that the CI was working, I decided to file an issue to Tue's repo and asked if I could help him test his text to HTML conversion. We worked with each other through Slack and GitHub, with myself taking notes of what he wanted to check and what the expected results should be. After struggling with managing and rebase commits when changing the code based on Tue's review, I was able to merge my pull request.

Conclusion

I intend to use continuous integration in additional projects in the future, and it was helpful to understand how it works and how to set it up. It makes collaboration considerably easier because it prevents unintended problems and code-breaking changes.

Happy coding! 💻

Performing code reviews

Luke Nguyen — Fri, 19 Nov 2021 03:54:21 +0000

Contributing to open-source doesn't stop at adding features and fixing bugs. Sometimes, you can do more than you might think just by performing code reviews. In this week of my open-source journey, I'll share some of my experiences when performing code reviews.

The project where I'll be doing this was my school IPC144 curriculum renewal. With many students working on the repository, it is essential to review and test incoming PRs regularly. Surprisingly, I didn't have any trouble looking for issues this time.

Here are the issues that I decided to perform the code reviewing on:

In the first issue, I wanted to check if the person escaped the special characters with "\," as some of them didn't get converted properly when formatting with Prettier. An example of this was on line 115-128, when the asterisks were replaced with underscores:

// Original
* Giga or G (=1024M): 1 Gigabyte = 1024 * 1024 * 1024 bytes ~ 10<sup>9</sup> bytes

// Expected
* Giga or G (=1024M): 1 Gigabyte = 1024 \* 1024 \* 1024 bytes ~ 10<sup>9</sup> bytes

// Actual
* Giga or G (=1024M): 1 Gigabyte = 1024 _ 1024 _ 1024 bytes ~ 10<sup>9</sup> bytes

For the second issue, I mainly focused on addressing what the contributor was missing in the list of requirements, specifically:

Using backticks and all code for memory addresses and such in tables that use things like void, int, function names, memory addresses.
Removing unnecessary changes

Code review is an excellent thing to do. By assisting others by leaving reviews and comments on the PR, not only will you improve the code quality of the PR, but you will also be able to learn some new stuff too.

To find out more about the problem in the first issue, you can check here.

Happy coding! 💻

Contributing to Telescope 🔭

Luke Nguyen — Thu, 18 Nov 2021 21:39:24 +0000

Introduction

While waiting for reviews in my recent pull request, I decided to find a different project. After hours of searching for issues on GitHub, I suddenly remembered the first repository where I made my first pull request, Telescope. Since then, the project has undergone many changes with different features and bug fixes, so I think it is time to make another contribution.

The issue

A quick overview about Telescope: it is a web server and application developed by professors and students at Seneca College to track students/faculties' blogs about anything open-source.

For my task, I had to customize Telescope's build log page to match the design and layout of the main dashboard, specifically:

Add header and side navigation bar
Change side navigation default logo into Telescope logo
Update link in side navigation logo to redirect to ./

Working on the issue

After setting up the development environment using Telescope's documentation, I began looking at the UI to figure out what I should do. Lucky for me, there was also a different issue that addressed the dashboard page UI, so I decided to use that as a reference.

I began by adding each UI component one by one, re-rendering the page every time I added in new code to make sure I didn't break anything. Once I was satisfied with my changes, I opened up a pull request on Telescope, explaining what I did and providing screenshots of the result.

Since I was referencing another issue, I had to keep track of the updated changes in the other PR and update mine accordingly. The other PR also had many requested changes, so I tried my best to read through all the reviews, adding comments when I needed help and clarification to ensure that I wouldn't break or miss anything.

Conclusion

Similar to the other PR, when this post is online, the PR is currently under review. I will constantly keep an eye on new notifications regarding this PR and add more commits if needed.

Cheers! 🍻

Contribution to course curriculum

Luke Nguyen — Thu, 18 Nov 2021 18:07:28 +0000

Introduction

Finally, I made it through Hacktoberfest! And, I also got myself a fancy new T-shirt! Celebration aside, I still have a lot of work to do. Working in open-source means you always have to be ready to look for new issues, find ways to contribute to the community of developers, and always set yourself up for new challenges. And this week, I had a chance to contribute to my school's course curriculum.

The project

The IPC144 course curriculum renewal is a project that aims to update the original course note to a brand new one using Docusaurus. As mentioned before in one of my blogs, Docusaurus is a static-site generator for building, deploying, and maintaining documentation websites. Most of the notes have already been changed to use Docusaurus, but the project needs contributions to review each converted section, add new features, or fix existing bugs.

The issue

After looking at all the available issues, I decided to go with adding static analysis tooling, specifically, installing and configuring Prettier as the source code formatter.

Working on the issue

Working on the issue was not too difficult, and I already have a different blog where I walk through how I setup Prettier, but here is an overview of what I did:

Installed Prettier using npm.
Added a .prettierrc file to configure all the options and a .prettierignore file to skip the ones that don't need formatting.
Added the necessary scripts to run Prettier in package.json.

Submitting the PR

Once I was satisfied with my work, I created a pull request and explained what I had done. Getting in touch with the project's maintainers was quick, as I could reach them through Slack. However, during the reviewing process, my professor (one of the maintainers) noticed an issue when Prettier formatted the Markdown files. Per my professor's request, I decided to alert other students working on auditing and fixing the documentation about this problem by filing a new issue. I made sure to write down a detailed explanation of how and why it happened while providing Prettier configurations so that other contributors could test their changes or replicate the issue if needed.

Conclusion

At the moment, the pull request was waiting to be merged. I will constantly keep track of any notifications and add changes if needed.

Happy coding! 💻

Automated testing with Jest 🤖

Luke Nguyen — Sat, 13 Nov 2021 02:09:12 +0000

Introduction

Managing code complexity can be difficult. I mean, you already added comments inside your codebase, wrote detailed documentation, and even set up static analysis tooling to keep your consistently formatted. But even so, somehow, your code still breaks. Human mistake? Bugs? It is hard to know. You can try adding safety nets to handle the errors, but can you even catch all of them?

Luckily, we have tests. Testing allows developers to prevent their existing code from breaking, identifies bugs, and tracks easy to miss edge cases. The added extra layer of protection ensures that your project, small or large, will evolve in the right direction when new changes are introduced.

What is Jest?

Since I wrote my project in JavaScript, I can choose between Mocha and Jest. In the end, I decided to go with the later option, as I have a bit of experience with it before.

A quick overview: Jest is a JavaScript testing framework that focuses on simplicity. It allows you to write tests and test suites in files ending with .spec.js or .test.js.

To begin, start by installing Jest using npm:

npm install --save-dev jest

Then, create a file with the ending as mentioned above to begin testing.

Writing tests

Because my project is a static site generator, I'll be testing the parsing logic that converts text to HTML.

First, I started by exporting and importing the necessary functions:

generate-html.js

module.exports = { generateHtmlBody, ... }

generate-html.test.js

const { generateHtmlBody, ... } = require('./generate-html')

With everything up and ready to go, I began thinking of how I should test the logic. Here are some example scenarios:

Checking if the paragraphs are wrapped in <p> tags. A paragraph is identified by having one or several consecutive lines of text, followed by a single blank line as a paragraph limit.
Checking if the title is wrapped in <h1> tags. A title is defined by being the first line followed by 2 blank lines.

Thus, my test should look something like this:

describe('generateHtmlBody tests', () => {
  test('returned html paragraph should be wrapped in <p> tag', () => {
    const data = 'Hello World!';
    const extName = '.txt';
    const title = null;

    const result = generateHtmlBody(data, extName, title);
    expect(result).toMatch(new RegExp(/<p>(.+?)<\/p>/g));
  });

  test('returned html title should be wrapped in <h1> tag', () => {
    const data = 'Hello World!';
    const extName = '.txt';
    const title = 'a title';

    const result = generateHtmlBody(data, extName, title);
    expect(result).toMatch(new RegExp(/<h1>(.+?)<\/h1>\n\n/g));
  });
});

Running the test

Great! We now have a file that tests for specific functionality, but how do we run it?

With Jest, setting up test scripts was not too difficult. Inside "package.json," add the following scripts:

{
  scripts: {
    "test": "jest --",
    "test:watch": "jest --watch --",
    "coverage": "jest --collectCoverage --"
  }
}

npm test [file] will run the test on the specified file.
npm run test:watch [file] will also run the test but in watch mode, which automatically re-runs when changes are made.
npm run coverage [file] will generate a code coverage report.

Conclusion

The experience of writing tests has forced me to challenge my way of thinking. Specifically, I had to abandon the thought of writing good tests every time and accepting that there would always be room for improvement. After all, there is no "done" in programming, only "version 1, 2, 3, and many more."

Free yourself from the need to be perfect. Embrace “better than it was” and continue living in that

Static Analysis tooling 🛠

Luke Nguyen — Sat, 06 Nov 2021 00:58:04 +0000

Introduction

It's easy to forget that people have different ways to write their code, from indentation, writing conditional statements, to choosing what type of quotes to use for strings. While this is trivial when working on personal projects, it is another story for projects with different people simultaneously working on a single code base. Unable to agree on a coding style often leads to problems reviewing pull requests, with developers/project maintainers spending countless hours searching for formatting issues instead of focusing on the logic.

With this in mind, open-source projects need to include static analysis tooling, as they help improve code maintainability by spotting suspicious coding constructs or alerting us to common errors.

Choosing the right tool 🔍

For my static site generator, which is written in JavaScript, I have selected Prettier and ESLint as the formatting and styling guide tools. I chose them due to their popularity amongst other developers, with detailed documentation and high customizability. Also, I have been using Prettier for a while as a VS Code extension, so it would be nice to learn more about it.

Using Prettier 🎨

To set up Prettier, start by installing the tool using npm:

npm install --save-dev --save-exact prettier

Then, follow the instructions from the Prettier docs and create 2 files: .prettierrc and .prettierignore

.prettierrc is where you will set all the configuration options for your Prettier formatting.
.prettierignore lets the Prettier CLI and editors know which files to not format.

Finally, add the necessary scripts to package.json:

{
  // ...
  "scripts": {
    "prettier": "prettier --write \"./**/*.{md,jsx,json,html,css,js,yml}\"",
    "prettier-check": "prettier --check \"./**/*.{md,jsx,json,html,css,js,yml}\""
  }
  // ...
}

Using ESLint 🧪

To set up ESLint, start by installing the tool using npm:

npm install eslint --save-dev

After finishing the installation, follow by setting up a configuration file, which you can do with:

npx eslint --init

You should ended up with something like this:

module.exports = {
  env: {
    commonjs: true,
    es2021: true,
    node: true,
  },
  extends: ['eslint:recommended', 'prettier'],
  parserOptions: {
    ecmaVersion: 13,
  },
  rules: {
    semi: ['error', 'always'],
    quotes: ['error', 'double'],
  },
};

The configuration file is where you can customize the validation rules based on the project. For more information about the rules, using plugins, or adding shared settings, refer to the ESLint configuration docs.

Finally, add the necessary scripts to package.json:

{
  // ...
  "scripts": {
    "eslint": "eslint --config .eslintrc.js",
    "eslint-fix": "eslint --config .eslintrc.js --fix",
    "lint": "npm run eslint",
  },
  // ...
}

Editor Integration 💻

Running static analysis tools at build time (i.e., using our scripts) is great since we can automate it. However, it would be nice to have a way to integrate them into our editor or IDE so that we can enjoy the benefits while writing code.

My solution is to create a .vscode/ folder that contains settings.json, which directly configures the VSCode editor settings, and extensions.json, which stores ESLint and Prettier as the recommended extensions.

Adding a pre-commit hook 🎣

Lastly, how can we deal with forgetful developers? The answer: adding a Git pre-commit hook. The hook will run your source code formatter on any changes that are being committed, preventing formatting errors before the developer makes a pull request.

For this task, I'll be using husky and pretty-quick. husky is a package for defining and executing git hooks, while pretty-quick is used to run Prettier formatting against your staged files.

First, start by installing husky and pretty-quick:

npx husky-init && npm install
npm install --save-dev prettier pretty-quick

This will setup husky, modify package.json and create a sample pre-commit hook that you can edit.

Inside package.json, modify the pre-commit script to use pretty-quick:

{
  // ...
  "scripts": {
    "pre-commit": "pretty-quick --staged"
  },
  // ...
}

After that, add the following code to /.husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo '🐶 Checking your commit...'
npm run pre-commit || echo '❌ Build failed. Please fix the error(s) showed above.'

And that's it! Every time you make a commit, the pre-commit hook will make sure to format the code using the configurations from .prettierrc.

Cheers! 🍻

Happy Hacktoberfest! 🎃 - Part 4

Luke Nguyen — Sun, 31 Oct 2021 05:08:00 +0000

Introduction

Well, this is it, the last chapter of my 2021 Hacktoberfest journey. As there wasn't much time left, I thought maybe I could get myself a project get it done quickly. Surprisingly, I was wrong.

Looking for a repository to work on during the last week of Hacktoberfest was quite challenging. As such, I had to rely on my classmates' PRs for issues. Since many of them worked on JavaScript or React-based projects, it didn't take me too long to find one. In the end, I decided to give Greenstand's Treetracker (an app for planting trees, surprisingly!) a shot.

The first issue

The first issue was to address a CSS behaviour that caused one of the pages not to scroll vertically. While cloning the project to my local machine, I discovered that I needed the admin credentials to log into Treetracker's website. After messaging one of the lead developers and asking for the credentials, I was added to a Slack server, which from there I could retrieve what I needed and begin my work.

Fixing the issue was not too hard. The source behind the unwanted behaviour was the overflow: hidden style in the Captures view, which I had to change into overflowY: scroll to make the page start scrolling again. After creating a PR, I got some feedback to make the navbar stick to the top even when scrolling. Googling for a solution, I realized that I had to move overflowY from the Captures view to the CaptureTable component, as this was the place that contained the navbar.

Finding a new bug

While working on the finishing touch for the CSS changes, I discovered another bug: the pagination kept loading the next page even when pressing the previous button.

The culprit lies on the CaptureTable component, where the page state was not set correctly when onPageChange happens. Realizing that it was an opportunity to test my knowledge of React, I decided to file an issue and asked if I could try and solve it myself.

First, I began looking up Material UI's TablePagination API per the lead dev suggestion. Using the example from the example and some inspiration from StackOverflow, I began creating the solution. The plan was to use a local page state, and when onPageChange happened, updated the page state to the value of the new page instead of page + 1:

const [page, setPage] = useState(captureContext.page);

const handlePageChange = (e, newPage) => {
    loadCaptures({
      page: newPage,
      // ...
    });
  };

While this solution was decent, I was told by the lead dev that the local state was unnecessary. He suggested taking advantage of the capturesContext context, which holds the logic to manage the page state. With his suggestion, I went back to the code and made some more adjustments, and in the end, managed to successfully merged my PR.

Conclusion

Hacktoberfest was an exciting new experience. I was able to learn a lot working with different communities on different projects and challenged myself to work on something a bit more advanced from what I learned. I'm excited to see which open-source events will happen in the future, and can't wait to contribute to even more repositories than this one.

Have a great Halloween everyone! 👻

Prototype: Markdown and static assets support for SSG 🛠

Luke Nguyen — Fri, 29 Oct 2021 20:20:49 +0000

Introduction

In the past two weeks, I had the chance to play around with Docusaurus, a React-based static site generator built and maintained by Facebook. Inspired by the feature-rich and beginner-friendly nature of the project, I decided to steal some of their ideas and apply them to my own.

Docusaurus impression 🐱‍🐉

Setting up Docusaurus was simple, and this is the command I used to create my Docusaurus website:

npx create-docusaurus@latest my-site classic

I chose the classic template as the starting point, since it already shipped with documentation, a blog, customs pages, and dark mode support using a CSS framework.

To deploy the site to GitHub pages, I had to make some modifcation to the docusaurus.config.js file:

{
  // ...
  url: 'https://mqnguyen5.github.io', // Your website URL
  baseUrl: '/docusaurus-demo/',
  projectName: 'docusarus-demo', // Your project's repo
  organizationName: 'mqnguyen5',
  // ...
};

After that, I just need to run GIT_USER=<GITHUB_USERNAME> yarn deploy, and there we go: A fully-fledged documentation website!

Docusaurus also make it easy for developers to add extra customization to their website, thanks to the organized directory structure, route-based modules, and excellent documentation.

Adding new features 💡

Currently, the implementation for markdown support is entirely hand-coded and is only available for a limited number of markdown syntax. To add full markdown support with this approach is just reinventing the wheel, and the better solution is to use an npm package to do the heavy lifting.

With the features in mind, I began by creating an issue on my repo, detailing what I needed to do, and providing suggestions or resources to help me accomplish it. Implementing the code was not too difficult, and I realized that I could add more features to improve my SSG. After being satisfied with how the markdown support works, I began editing the issue to include support for static assets. It is a nice feature to have in my project, as I think images and favicons are common in most web pages today.

While working on the feature for static assets, I realized that I couldn't find a way to customize markdown.it (the packages used for markdown support) to refer to the newly created /assets folder. As such, I had to develop a workaround by using regex, and in the end, managed to make it work.

Conclusion

While I managed to implement the features, I was still unsatisfied with the result. The static assets support could be buggy, and there is still room for improvement. Additionally, I planned on adding frontmatter support to make the web pages more optimized for search engines, but it was postponed as I needed to deal with the static assets issue. I managed to file some issues for those leftovers, which I will be working on soon when I have the time. For those who are interested, the issues are #issue-16 and #issue-17, available in my GitHub repo.

Cheers! 🍻

DEV Community: Luke Nguyen

Release 0.4 - Part 3

Introduction

The issues

1. #issue-2416

2. #issue-107

Conclusion

Release 0.4 - Part 2

Introduction

Working on the issues

1. #issue-2416

2. #issue-107

Conclusion

Release 0.4 - Part 1

Introduction

The search 🔎

Planning 📝

1. #issue-2416

2. #issue-107

Publishing a project to npm

Introduction 📖

Preparing for release 🛠

1. Making the project callable by its name

2. Testing the project locally

3. Adding information to package.json

Releasing to npm 💾

Receiving users' feedback

Conclusion

Adding Continuous Integration with GitHub Actions 🛠

Introduction

Choosing a CI

Setting up the CI

Writing test for others

Conclusion

Performing code reviews

Contributing to Telescope 🔭

Introduction

The issue

Working on the issue

Conclusion

Contribution to course curriculum

Introduction

The project

The issue

Working on the issue

Submitting the PR

Conclusion

Automated testing with Jest 🤖

Introduction

What is Jest?

Writing tests

Running the test

Conclusion

Static Analysis tooling 🛠

Introduction

Choosing the right tool 🔍

Using Prettier 🎨

Using ESLint 🧪

Editor Integration 💻

Adding a pre-commit hook 🎣

Happy Hacktoberfest! 🎃 - Part 4

Introduction

The first issue

Finding a new bug

Conclusion

Prototype: Markdown and static assets support for SSG 🛠

Introduction

Docusaurus impression 🐱‍🐉

Adding new features 💡

Conclusion

3. Adding information to `package.json`

Releasing to `npm` 💾