A woman using her laptop in a public space, facing tall glass windows
Photo by Bonnie Kittle on Unsplash

I started Freelancing In India: A Handbook a lit¬≠tle over two years ago, cov¬≠er¬≠ing much of my prior ex¬≠pe¬≠ri¬≠ence in the Ô¨Ārst six months of cre¬≠at¬≠ing the repo. It was just a sim¬≠ple README.md Ô¨Āle view¬≠able on GitHub.

Over time, it gained a small but re­spectable num­ber of stargaz­ers. Seeing this, I de­cided it was time to move it to some­thing more struc­tured and more eas­ily view­able.

I also wanted to ex­pand the scope of the pro­ject from just work­ing with in­ter­na­tional clients to SaaS of­fer­ings, paid ap­pli­ca­tions on app stores, work­ing with do­mes­tic clients, and so on.

I don‚Äôt have much Ô¨Ārst-hand in¬≠for¬≠ma¬≠tion on these as¬≠pects, but I‚Äôm count¬≠ing on the few re¬≠sources I‚Äôve found on¬≠line to make for a suf¬≠Ô¨Ā¬≠cient start¬≠ing point and the com¬≠mu¬≠nity to step in!

VuePress

I de¬≠cided to use VuePress for its promise of sim¬≠plic¬≠ity. I got started in about a cou¬≠ple of hours, with very lit¬≠tle frame¬≠work Ô¨Āght¬≠ing to do. It al¬≠most just worked. Had I had prior ex¬≠pe¬≠ri¬≠ence with it, I doubt I would have spent even as much time as I did.

The de­fault theme is great, and even comes with these lit­tle bal­loon-style con­tain­ers for tips, warn­ings, dan­ger, and more. Here’s an ex­am­ple of a warn­ing from the site it­self:

A warning as seen on the documentation

It also in¬≠cludes a very easy to use search bar, a home page tem¬≠plate, and the abil¬≠ity to add to nav¬≠i¬≠ga¬≠tion. Although not vis¬≠i¬≠ble in the screen¬≠shot be¬≠low, it also has a last up¬≠dated time¬≠stamp for every page to re¬≠Ô¨āect on the re¬≠cency of the in¬≠for¬≠ma¬≠tion. It‚Äôs also fully re¬≠spon¬≠sive! Being server-side gen¬≠er¬≠ated, we ab¬≠solutely don‚Äôt lose out on SEO. ūüėĀ

A full screenshot of the documentation, with a sidebar navigation and a search bar with the input "import" and its search results

My only gripe?

I wish there was an op¬≠tion to gen¬≠er¬≠ate the side¬≠bar links au¬≠to¬≠mat¬≠i¬≠cally. At the mo¬≠ment, you need to spec¬≠ify it man¬≠u¬≠ally in the con¬≠Ô¨Āg¬≠u¬≠ra¬≠tion Ô¨Āle, like so:

// .vuepress/config.js
sidebar: [
"/docs/",
"/docs/getting-started",
"/docs/defining-export",
"/docs/getting-paid",
"/docs/gst-returns",
"/docs/income-tax"
],

Of course, the con¬≠trol and Ô¨āex¬≠i¬≠bil¬≠ity is great. Still, a con¬≠Ô¨Āg¬≠u¬≠ra¬≠tion op¬≠tion to let VuePress parse the di¬≠rec¬≠tory and build the tree on its own would have been amaz¬≠ing. In sce¬≠nar¬≠ios where we wish to in¬≠clude every¬≠thing, it would be very handy.

However, spec¬≠i¬≠fy¬≠ing the side¬≠bar nav¬≠i¬≠ga¬≠tion is a mat¬≠ter of Ô¨Āve to ten min¬≠utes at most. It is far from a deal breaker.

Final take

With all the boil­er­plate taken care of, VuePress was re­ally en­joy­able to set up and I will def­i­nitely con­sider it again for any kind of doc­u­men­ta­tion. It claims to be geared more to­wards tech­ni­cal docs, but worked just as well for my hand­book.

Now it‚Äôs time for me to Ô¨Ānd con¬≠trib¬≠u¬≠tors. ūüôā