Last week, I was looking for a repository to contribute to. Looking for a repository to contribute is always the hardest step, because you need to adapt to the new project, get used to the code structure, and you have to learn a lot of things about the codebase before contributing something meaningful.🥵🥵
After searching for a while, I found Hexo, an SSG. I was interested on working on this one since I am working on an SSG myself. I thought, "maybe I can get some inspiration from them on how to approach the design of my SSG🕵️♀️🕵️♀️"
I skimmed through the issues list, until I found one that seemed manageable for my level, issue #4516: Only show line number when number of lines of code greater than a threshold! We can guess the feature requested just by reading a title: implement an option to conditionally show line numbers on code blocks if the number of lines of the code blocks exceed a certain number.
Although I said manageable, I have to admit I was a little bit lost on how Hexo worked, since I haven't used the application at all. I underestimated my abilities🙈🙈🙈. It wasn't until I cloned the code and played around with it by reading the documentation until I understood how Hexo was organized.
Hexo rough structure
❗❗DISCLAIMER❗❗: Whatever I am saying here, don't take it as truth, since I am not a proper maintainer of the Hexo codebase. I am speaking totally from my experience and understanding after dabbling through the codebase for a few hours.
The Hexo codebase is divided into the core, which is shipped as a library in a npm package, a CLI front-end, normally named hexo-cli, and plugins, which can be official and third-party plugins.
Most of the processing happens in the core, while certain features like formatting for codeblocks, blockquotes, etc, is given by plugins like prismjs or highlightjs. Of course, the plugins are like an intermediate layer between the core and the external dependencies (prismjs, for example).
There is a plugin that handles the code tags, and that's where I started doing my changes. The file is called code.js.
The logic was fairly simple: accept a new option called line_threshold of type number. If the line_number flag (the flag that toggles the line numbers in the code block) is passed as true, we will then need to check that the current text has enough lines to surpass the threshold. For example, if the text was 3 lines long, but our threshold is 3, then the line numbers will not be shown, before the number of lines is not greater than the threshold.
I did some slight modifications so that we can accept that argument directly from code blocks written in the file: {% codeblock line_threshold:3 %}...{% endcodeblock %}, as well as from a YAML file configuration.
You can view the changes in my PR.😁
Some experience to share...
I think I am starting to learn more and more on how to adapt to a new codebase, specially when I want to focus on a specific issue. The idea is that I focus on the issue itself, while slowly uncovering the structure of the code along the way. Also, trying to uncover how the program runs at all by actually running it does help, as well, but it might be more time consuming. I was lucky that the issue I worked on was well isolated. I am thankful that the Hexo team is able to achieve such a level of modularity so that even a new contributor can head first into the codebase🌈🥰.
Top comments (0)