The goodness of GitHub Pages, VuePress, and Markdown

Photo by Hannes Wolf on Unsplash

Documentation is the most needed deliverable for any product or project. Sometimes, documentation is the deciding factor while choosing between two equally good frameworks/libraries in the open-source community.

Markdown played a major role in encouraging developers to do quick documentation without leaving their IDE. Importantly, Markdown fits well into the Git/source code control.

A new kind of documentation has started, which provides an interactive playground. Developers can explore the features of the product/components and can copy the code snippet. For example, check the following Vuetify component page

Card component

Storybook allows documenting your component using Markdown and JSX (MDX). Storybook’s inflexibility and mix-up of testing scope make it a second choice for documentation.

If you like the new generation documentation, but don’t have time to create the boilerplate code required, don’t worry. VuePress is there for your rescue.

Finally, you would prefer to host the static pages for everyone’s access. GitHub covers the base for you.

Getting Started with GitHub Pages — Reference

• Create a new GitHub account (if required)
• Create a new public repository named username.github.io, where username is your username (or organization name) on GitHub.

Getting Started with VuePress — Reference

mkdir username-docs && cd username-docs
yarn init
yarn add -D vuepress
mkdir docs && echo '# Hello VuePress' > docs/README.md
Edit package.json and include the following scripts
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
Run the local server using the following
yarn docs:dev

Deployment to GitHub Pages — Reference

Inside your project, create deploy.sh with the following content (with highlighted lines changed appropriately), and run it to deploy

#!/usr/bin/env sh

# abort on errors
set -e

# build
npm run docs:build

# navigate into the build output directory
cd docs/.vuepress/dist

# if you are deploying to a custom domain
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# if you are deploying to https://<USERNAME>.github.io
git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

cd -

💡For deploy.sh script to work, you need to do SSH setup for your GitHub account . Instructions are provided here

I have followed all the above instructions and created my hobby website — Still under construction

Source Code — GitHub Repo Link

The codebase is self-explanatory. Please check “VuePress Getting Started” for step-by-step instructions.

Always Free

VuePress Google Analytics plugin is not working due to recent changes in GTag. Check the following code snippets if Google Analytics set up is required.

// .vuepress/config.js
module.exports = {
  head: [
    ...googleAnalytics('G-Z07GXXXXXX')
  ],
}

Conclusion

Documentation can be casual or formal. I have started documenting my notes, cheat sheets, and code snippets using Markdown and VuePress. I hope the ideas herein help your team. Feel free to let us know in the comments.