git2blog

📋 Overview

git2blog is a lightweight, Node.js-powered static site generator and server. It automatically synchronizes Markdown files from a specified GitHub repository and serves them through a clean, searchable web interface. It’s designed to be minimal, dependency-light, and perfect for developers who want to manage their blog posts directly via GitHub commits.

📥 Installation

1. Clone the repository:

git clone https://github.com/nhrx1337/git2blog.git

cd git2blog/

2. Install dependencies:

npm install

⚙️ Configuration

Before starting the server, you need to point the application to your specific GitHub repository:

1. Open services/github.js.

2. Update the following constants with your GitHub details:

const REPO_OWNER = 'your-github-username'; 
const REPO_NAME = 'your-repository-name';

3. Create a .env file in the root directory:

# Optional: Provide a GitHub Token to avoid Rate Limiting (60 req/hr vs 5000 req/hr)
GITHUB_TOKEN=your_personal_access_token_here

4. Start the server:

node server.js

▶️ Usage

• Once started, the server runs on http://localhost:8000.
• The system automatically fetches files from the target GitHub repository every 30 minutes.
• Select a file from the sidebar to render its content as HTML.
• Dynamic Updates: If a file is deleted or updated on GitHub, the local state and /posts directory will be synchronized automatically.

⚙️ Behavior & Notes

• State Management: Uses a state.json file to track GitHub SHAs, ensuring files are only downloaded if they have changed.
• Content Sync: Automatically handles file creation, updates, and deletions based on the remote repository state.
• Environment Aware: Supports optional .env files for GitHub API authentication to increase rate limits.

🧩 Dependencies

• Node.js: Built-in modules (http, https, fs, path).
• marked: Markdown parsing engine.
• dotenv: Environment variable management.

📁 Project Structure

git2blog/
├── posts/               # Synchronized Markdown files from GitHub
├── public/              # Static assets and UI templates
│   ├── images/          # Image assets
│   ├── index.html       # Main blog template
│   ├── script.js        # Theme toggle & client-side logic
│   └── style.css        # UI styling
├── services/            # Core logic and helper services
│   ├── github.js        # GitHub API & file sync service
│   └── state.js         # Local state & SHA tracking
├── .env                 # Environment variables (GITHUB_TOKEN)
├── package.json         # Project metadata and dependencies
├── server.js            # Entry point - HTTP server & routing
└── state.json           # Persistent sync state (auto-generated)

🧹 Maintenance

To reset the local cache and force a complete re-sync from GitHub:

• Delete the posts/ directory.
• Delete the state.json file.
• Restart the server.

📸 Previews