Setup and continuously deploy your documentation on Github in under five minutes (Nuxt Content + Github Pages/Actions)
You have a repository on Github and want to add documentation to it. You may already have documentation that you are building locally and publishing somewhere, but you want to up your game.
There are a few features you’d like in that new shiny documentation, like
- Written in Markdown
- Full-text search for your users
- Syntax highlighting to code blocks
- Table of contents generation
- Dark Mode
- Multi-language support
- Offline-support (PWA)
- Blazing fast hot reload in development
- Extendable with Vue components
- Beautiful and clean design (Tailwind based maybe)
- ….
Phew. You are thinking about creating a new framework. Your head is spinning. That’s going to take a while. That’s where you are wrong kiddo.
Nuxt (Vue framework for SSR/SSG/SPA) and it’s content module lets us set up our documentation in no time with all the fancy features from above. We’ll make use of Github pages to host the documentation and Github Actions to continuously deploy. Let’s get started.
Navigate to your project and initialize the Nuxt project using Nuxt content and the docs theme.
# Enter project directory
cd github-nuxt-content-docs# Setup in the docs directory
yarn create nuxt-content-docs docs
Answer the questions truthfully, as my project’s repository is kevcodez/github-nuxt-content-docs, here are the sample answers:
? Project name: github-nuxt-content-docs
? Project title: Github Nuxt Content Docs
? Documentation url: https://kevcodez.github.io/github-nuxt-content-docs
? GitHub repository (owner/name): kevcodez/github-nuxt-content-docs
? Twitter username (@username): kevcodez
? Package manager: Yarn
Coolio, all set here. You may have to delete the .git directory under the docs folder, because you are already in a git repository.
To continuously deploy our documentation, we need to set up a CI/CD. You can use Travis, CircleCI or whatever floats your boat — we will be using Github Actions to keep it simple. GitHub Actions is Github’s CI/CD to build, test and deploy code right from Github. To do so, we’ll add a custom workflow under .github/workflows
mkdir -p .github/workflowsCreate a docs.yml file.
Push your changes and check the Actions tab in Github. This action will generate your docs and publish it to a separate branch (gh-pages). The only thing left to do is setup Github Pages under the Settings tab in your repository.
Scroll all the way down to “Github Pages” and select the gh-pages branch and the root folder as source. You can also add a custom domain if you like. The URL of your documentation will be https://<github-username>.io/<repo-name> by default.
You have successfully set up your documentation and continuous deployment. Let’s make a few adjustments and our first actual deployment of the docs.
Since your docs won’t be available on the domain root (/), but on a sub path (/repo-name), we have to adjust the config a bit. Go to docs/nuxt.config.js
Last but not least, edit the docs/content/settings.json file as it contains absolute paths for the logos.
Push your changes and see the magic for yourself. Check the actions tab on Github. After just a minute, your changes will be live.
Bada bing bada boom. You just set up a continuous deployment for docs living in your repository with many awesome features such as markdown editing, superb performance, dark mode, multi-language support and so on.
Head over to your docs folder and run yarn dev to start editing your documentation. Head over to the official Nuxt Content docs to learn more about writing your docs.
Oh, and it’s completely free and open-source. I’d love to see your documentation when you’ve tried it out. Feel free to follow me on Twitter in case this was any helpful.
