The problem
I wanted to build a zero-or-almost-zero-config documentation system to use at our office to move away from a hell of ODT, PDF files scattered around a file server. You know what I’m talking about 😁
Long story short, I’ve settled on Vuepress when I found this awesome plugin to auto generate the sidebar and the navbar based on the directory structure: I think that the approach of convention over configuration is one of the strongest and easiest, especially if you want the team to be able to write docs from the get go.
During the testing phase I’ve noticed a strange behaviour when navigating in different sections (in Vuepress lingo: the top bar), as defined by the directories with the nav.directory name: every link there would result in a 404.
Have you ever experienced the moment in which you say to yourself
Is it possible that even following the docs/guide/tutorial to the last paragraph, I cannot replicate the awesome result the author presented?
Been there? I’ve been there a lot, but this time I thought I could dig into it, and maybe help in fixing a problem so others wouldn’t have to go through this hurdle.
Debugging Vuepress
The first evidence I found that put me on track was seeing that the link destination for the links in the navbar were malformed or just plain wrong, not prepending the base URL and with the page name missing:
# rendered href
https://nav.directory/.html
# desired href
http://localhost:3000/nav.directory/index.html
I hopped in the awesome Vue Dev Tools and started digging in the Vue component props created by the dev server and noticed that the $site.themeConfig.navbar and $site.themeConfig.sidebar parameters, generated by the vuepress-bar plugin had malformed values, like:
"sidebar" : {
"/": {...},
"\nav.directory\": {...},
"\nav.directory2\": {...}
}
The backslash characters put me on the right track, because that’s what Windows uses as a directory separator by default. To dissipate any shade of doubt I tried the same exact config inside a Linux Docker container and actually it worked as expected.
Opening the issue
Identified the possible cause, I went to the vuepress-bar Github repo and opened this issue.
The process is pretty straightforward:
- Selected the issues tab
- Made sure that no one else already filed the same problem (not many Windows users these days I guess)
- Clicked the
New issuebutton - Tried to be as descriptive as possible but concise at the same time to not waste the developer’s time, including examples of the rendered html and the desired result
Finding a possible solution
Digging inside the actual plugin folder in node_modules/vuepress-bar and after a few minutes of reading someone else’s code, who is way more experienced than me, I finally got to the offending line.
Three attempts later and testing with a few different configs, I finally settled on a solution, which is probably quick and dirty, but at least appears to fix the problem.
Proposing my fix by making the pull request
To propose the author my changes, I needed first to fork the repository by clicking the fork button at the top of the repo. Next, I cloned it locally via the command
git clone https://github.com/nirebu/vuepress-bar
Opened the folder in VS Code and made the same changes I made inside the node_modules and pushed the change to my forked repo using these commands
git add . # to add all the files changed, in this case just one
git commit -m "Adjusted the nav link separator on Windows" # to describe what my change would do if applied
git push origin master # to actually upload my changes to my forked repository
Now it was only a matter of opening the actual pull request, to notify the author about my change. To do so, I clicked the Pull requests button in the repository navigation bar and next the New Pull Request.
To select my repository as a source of changes I needed to select the Compare across forks link, and then it was as easy as selecting the HEAD commit (the most up to date) of my forked repository master branch. The result was this.
Phew, done.
Now let’s wait for the author to review and approve, comment or reject my pull request right away.
Closing thoughts
Contributing to someone else’s project can be a daunting process because, apart from the technical aspects, there are plenty of psychological factors involved like impostor syndrome and fear of rejection.
I’m sure my proposal isn’t the best one or the most elegant, but at least I’ve overcome the initial wall and tried. When I’ll become more proficient in my programming skills I’ll make sure to contribute even more to other people’s projects: it’s a way of giving back to a community that alredy have given me much.