Adding Full Markdown Support and Sidebar Menu to My OpenSSG

This week I had a look at Docusaurus which provides a simple React website generation. Especially it provides a lot of support for markdown document. Sidebar menu can be easily configured and adding themes and translations require minimum effort. Deployment took me only a few minutes.

It is a very interesting open source project created by Facebook. It provides document search, SEO, static assets, plugins, and many more. I would like some of these features in my OpenSSG. But considering that my SSG is not mature enough to implement high level features, I decided to add some of fundamental ones which is full markdown conversion support, adding sidebar menu, and default CSS support. I will implement more whenever my time allows.

I spent some time on ways to implement full markdown support. Current markdown conversion logic is already complicated and I felt that I was doing very low-level programming. So I searched Java libraries to make this job faster and easier, then I found Commonmark. I'm still not familiar with configuring Java dependencies, but I'm very satisfied with the full markdown syntax test. At the same time, I could reduce my complex markdown parsing code. After that, I looked at how to add sidebar menu. Instead of allowing users to configure their own sidebar, I decided my sidebar has same tree hierarchical structure from input files. This was also pretty challenging to me. But I could handle this logic with my own tree data structure class called DOMNode class. I also had a chance to use recursive function to complete path from each tree node.

public String getUrl() {
        if (this.parent == null){
            return ".";
        }
        return this.parent.getUrl() + "/" + this.data;
    }

It was amazing that I could use this technique in real world programming

Lastly I added default CSS support as it requires to support sidebar.

Planning my feature rollout was great. Some work needs prerequisite or existing class change, in overall the order of my feature plan went nice and smooth although my implementation wasn't fast. I will add static asset support, then I will think about more of configuration to support configurable sidebar, themes, and plugins, etc.

I think prototyping is a proof of concept to make sure that the solution is feasible and check if there is any missing consideration to complete the feature. For me, I needed to make sure that DOMTree class works as I expected since I didn't implement tree node before. It was very helpful to prove my concept with a prototype.

I wrote issues of short-term features and will have to write long-term issues. From my experience in Hacktoberfest, I think I should add more details to README how to set up dev environment, so that contributors don't get frustrated. Also issue should be clear what to implement or fix. Without clear understanding it's not easy to try to get involved. At the same time, feature should be interesting enough to have someone take the challenge.