How to Deploy A Docsify Site to GitHub Pages

Build and Deploy a Docsify Site to GitHub Pages 🚀

Welcome!

If you want to build a Docsify site and push it to GitHub Pages, you've arrived at the right tutorial!

Docsify is a markdown-powered static site generator that doesn’t require a build process. And the best part? You can deploy it to GitHub Pages in minutes.

Let's get started!

---

1. Prerequisites 📋

Before diving in, make sure you have:

• Node.js & npm installed (Docsify requires them)
• A GitHub account (You’ll need this for deployment)
• Git installed (to push your site to GitHub)

To check if you have Node.js installed, run:

node -v

If you see a version number, you’re good to go. If not, you can download it from nodejs.org.

---

2. Install Docsify-CLI

Docsify has a CLI, which makes setup easier. Install it globally with:

npm install -g docsify-cli

Now, you can generate a new Docsify site in seconds using this tool.

---

3. Set Up Your Docsify Site 📂

Create a new directory and then move into it:

mkdir my-docs-site && cd my-docs-site

Then, initialize your Docsify site:

docsify init ./

This creates:

• index.html - Entry file
• README.md - Homepage content

Want to see your site? Run:

docsify serve

Then open http://localhost:3000/ in your browser, and your new site will be up and running 🎉

---

4. Customize Your Site 🛠️

Open index.html and tweak the <title> or theme settings. Docsify supports different themes, and you can configure sidebar navigation, plugins, and more. Check out the Docsify docs for customization options.

💡 Pro Tip: If you have a GitHub repo already and just want docs for it, you can generate 4-7+ pages about the library (including a getting started guide etc) using this documentation generator for Docsify. You can export the full code and deploy it to GitHub quickly.

This can be useful if you'd like to quickly scaffold the documentation pages for your repo.

---

5. Deploy to GitHub Pages 🚀

Step 1: Initialize a Git Repository

Inside your Docsify folder, run:

git init

When adding files to git, you can specify to ignore unnecessary files by adding a .gitignore file to your directory. One way is through the command-line, but you could also create a new file in your code editor and then save it.

echo "node_modules/" >> .gitignore

Step 2: Create a GitHub Repository

When you're ready to publish your new site, it's time to create a new GitHub repo!

Go to GitHub and create a new repository. One of the options will be to initialize a README, but since we already have one, there's no need to select this.

Now, link your local repo to GitHub:

git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO

Step 3: Commit and Push Your Docsify Site

git add .
git commit -m "Initial Docsify site"
git branch -M main
git push -u origin main

Step 4: Enable GitHub Pages

1. Go to your repo on GitHub.
2. Navigate to Settings > Pages.
3. Under Branch, select main and click Save.
4. Your site will be available at https://YOUR_USERNAME.github.io/YOUR_REPO/ after a few minutes. 🎉

Adding A Docs Site To A GitHub Repo

If you already have a library or code repo (with your code) and want to add documentation to this, you can add a docs folder to your repo and include the Docsify site there.

Then when you enable GitHub pages for your site, any time you push to the docs directory, your site will be automatically updated.

---

Wrapping Up

Docsify makes it intuitive and seamless to build and deploy a markdown-based documentation site.

And with just a few commands, your docs are live on GitHub Pages.

Hopefully you've found this guide useful, and let me know if you have questions. I'm always glad to help!

Thanks for reading!