You've built a beautiful, organized knowledge base using Markdown — now it's time to share it with the world. In this guide, you'll learn how to deploy it quickly and for free using GitHub Pages.
Step 1: Organize Your Markdown Files
Start with a simple structure:
knowledge-base/
├── index.html
├── styles.css
├── scripts.js
└── docs/
├── getting-started.md
├── usage.md
└── faq.md
Make sure your index.html
file is set up to display and link to your Markdown files.
Step 2: Initialize a Git Repository
In the root of your project:
git init
git add .
git commit -m "Initial commit"
Push it to a GitHub repository:
gh repo create my-knowledge-base --public --source=. --remote=origin
git push -u origin main
Step 3: Enable GitHub Pages
- Go to your GitHub repo.
- Click Settings > Pages.
- Under Source, select the
main
branch and/ (root)
folder. - Click Save.
Your knowledge base will be live at:
https://your-username.github.io/your-repo-name
Step 4: Serve Markdown Files Correctly
If you want Markdown files to render as HTML in the browser, use a client-side Markdown parser like Marked.
Example in scripts.js
:
fetch('docs/faq.md')
.then(res => res.text())
.then(md => {
document.getElementById('content').innerHTML = marked(md);
});
Your index.html
might include:
<div id="content" class="prose mx-auto px-4"></div>
✅ Pros and ❌ Cons of Using GitHub Pages
✅ Pros:
- 🚀 Free hosting
- 🔄 Auto-deploy with Git
- 🔒 HTTPS by default
- 🧩 Works great for static content
❌ Cons:
- 🛠 No backend features (form handling, auth)
- ⚠️ Markdown rendered via JavaScript (not ideal for SEO)
- 🌐 Limited to static sites
Summary
GitHub Pages offers a fast and free way to host your Markdown-based knowledge base. With a bit of HTML and JavaScript, you can create a searchable, organized, and responsive system that’s easy to deploy and update.
📘 Want to build a more advanced knowledge base?
Check out my 20-page guide, Creating a Flexible Markdown Knowledge System. You'll learn how to:
- Structure, tag, and search your content
- Build responsive layouts with Tailwind
- Deploy using GitHub Pages, Netlify, and more Just $10.
If this article helped you, feel free to buy me a coffee ☕
Top comments (0)