GitHub Comments System – File Directory

Complete list of files for the GitHub comments system.

📁 File Structure

Source Code (src/cloudflare/):

src/cloudflare/
├── comments.js                 (12 KB) ← Main server handler
├── standard.comment.js          (9.5 KB) ← Browser library
├── comments-example.js         (2.7 KB) ← Cloudflare endpoint
├── wrangler-comments.toml.template (3.3 KB)
├── wrangler.toml.template      (already exists)
├── utils.js                    (already exists)
└── example.js                  (already exists)

Documentation (content/cloudflare/comments/):

content/cloudflare/comments/
├── COMMENTS-QUICK-START.md     (8 KB) ← Start here (10 min setup)
├── COMMENTS-GUIDE.md           (12 KB) ← Full documentation
├── COMMENTS-FILES.md           (this file)
├── comments-template.html      (9.7 KB) ← Complete HTML+CSS
└── index.md                    ← Overview & navigation

📄 File Details

Core Implementation

comments.js (12 KB)

Purpose: Server-side comment handler for Cloudflare Functions

Key Exports:

• handleComments(request, env) – Main handler function
• handleCommentSubmission(data, env) – Process comment
• getCommentsFromGitHub(pageId, env) – Fetch comments
• submitToGitHub(file, env) – Save to GitHub

Functions:

• generateCommentId() – Create unique IDs
• sanitizeHTML(content) – Remove XSS
• validateComment(data) – Validate input
• detectSpam(comment) – Spam detection
• getGitHubHeaders(env) – GitHub API auth
• createCommentFile(pageId, comment) – Format file
• sendModerationEmail(comment, spamDetection, env) – Alerts

Configuration:

• GITHUB_TOKEN – GitHub authentication
• GITHUB_OWNER – GitHub user/org
• GITHUB_REPO – Repository name
• GITHUB_COMMENTS_PATH – Storage path
• SPAM_CHECK_ENABLED – Enable spam detection
• MODERATION_EMAIL – Moderator email

Lines: ~400 (well-documented)
Dependencies: Built-in fetch, no npm packages

standard.comment.js (9.5 KB)

Purpose: Browser library for rendering and form handling

Class: GitHubComments

Key Methods:

• load() – Fetch comments from API
• submit(data) – Submit new comment
• render() – Render comment tree
• attachFormHandler(selector) – Setup form
• startPolling() – Enable real-time updates
• stopPolling() – Disable polling

Utilities:

• formatTime(dateStr) – Relative timestamps
• formatContent(content) – Markdown to HTML
• escapeHTML(text) – XSS prevention
• buildCommentTree() – Nested structure
• renderTree(comments, level) – Recursive render

Configuration:

• apiUrl – Comments API endpoint
• pageId – Unique page identifier
• container – Where to render comments
• form – Comment form selector
• pollInterval – Update frequency (optional)

Lines: ~350
Dependencies: None (vanilla JavaScript)

comments-example.js (2.7 KB)

Purpose: Ready-to-deploy Cloudflare Workers function

Exports:

• default handler object with fetch method

Middleware:

• validateEnvironment() – Check required vars
• handleCorsMiddleware() – CORS preflight
• logRequest() – Request logging
• Error handling and response wrapping

How to Use:

cp comments-example.js functions/api/comments.js
wrangler publish --env production

Lines: ~60
Dependencies: comments.js, utils.js

Configuration

wrangler-comments.toml.template (3.3 KB)

Purpose: Cloudflare Workers configuration template

Sections:

• [env.development] – Local development
• [env.staging] – Staging environment
• [env.production] – Production environment

Environment Variables:

• Required: GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, GITHUB_COMMENTS_PATH
• Optional: MODERATION_EMAIL, GITHUB_WEBHOOK_SECRET, SPAM_CHECK_ENABLED

How to Use:

cp wrangler-comments.toml.template wrangler.toml
# Edit values
wrangler secret put GITHUB_TOKEN --env production

Templates & Examples

comments-template.html (9.7 KB)

Purpose: Complete HTML + CSS template for integration

Components:

• HTML form with author, email, content fields
• Comments display container
• Inline CSS styling (can be extracted)
• JavaScript initialization code
• Responsive design
• Accessibility features

Sections:

1. Comments header
2. Comments container
3. Comment form
4. JavaScript setup
5. CSS styling (embed or link)

How to Use:
Copy form HTML into your article template, include CSS, and add JavaScript initialization.

Documentation

COMMENTS-QUICK-START.md (8 KB)

Start here! 10-minute setup guide.

Sections:

• Files included
• Setup in 3 steps
• Minimal example
• Environment variables
• Key features
• File structure
• API endpoints
• Common issues
• Advanced features

Best For: First-time setup, quick reference

COMMENTS-GUIDE.md (12 KB)

Complete documentation for the comment system.

Sections:

• How it works (diagram)
• Features list
• Setup instructions (detailed)
• Comment file structure
• Moderation workflow
• API reference (full)
• Advanced usage
• Email integration
• Troubleshooting
• Security considerations
• Deployment checklist

Best For: Deep understanding, advanced features, troubleshooting

COMMENTS-FILES.md (this file)

File reference and quick directory.

Sections:

• File structure diagram
• Detailed description of each file
• Size and stats
• How to use each file
• Which file to read first

Supporting Files (Already Exist)

utils.js (5 KB)

Shared utility functions used by comments system.

Exports:

• corsHeaders – CORS headers object
• handleCORS() – CORS middleware
• createResponse() – Format responses
• createErrorResponse() – Format errors
• parseRequest() – Parse incoming request
• withCache() – Add cache headers
• validateMethod() – Check HTTP method

Used By: comments-example.js, other endpoints

example.js (1.5 KB)

Example Cloudflare function showing utilities.

Purpose: Demonstrates how to use standard utilities pattern

See Also: comments-example.js for similar pattern

README.md (5 KB)

General Cloudflare documentation for Standard Framework.

Sections:

• What is Cloudflare Functions
• File organization
• Getting started
• Deployment
• Environment setup

USAGE.md (6 KB)

General usage patterns for Cloudflare Functions.

Sections:

• How to deploy
• Environment variables
• Testing locally
• Debugging
• Performance tips

SUMMARY.md (5 KB)

Overview of the Cloudflare integration with Standard Framework.

Sections:

• What’s included
• File structure
• Setup checklist
• Next steps

QUICK-REF.md (4.5 KB)

Quick reference for common Cloudflare tasks.

Sections:

• Common patterns
• Code snippets
• Troubleshooting
• FAQ

📊 File Statistics

🚀 Getting Started

Which file should I read first?

1. New to this? → Read COMMENTS-QUICK-START.md (10 min)
2. Need full details? → Read COMMENTS-GUIDE.md (30 min)
3. Ready to code? → Copy comments-template.html + comments-example.js
4. Troubleshooting? → Check COMMENTS-GUIDE.md troubleshooting section

How do I deploy?

1. Copy comments-example.js → functions/api/comments.js
2. Copy wrangler-comments.toml.template → wrangler.toml
3. Edit wrangler.toml with your GitHub details
4. Run wrangler secret put GITHUB_TOKEN
5. Run wrangler publish --env production

Where’s the HTML?

Copy comments-template.html into your site template. It includes:

• Complete form
• Inline CSS
• JavaScript initialization
• No external dependencies

What about the JavaScript?

standard.comment.js provides the GitHubComments class:

const comments = new GitHubComments({
  apiUrl: '/api/comments',
  pageId: 'blog/my-post',
  container: '#comments',
  form: '#comment-form'
});

await comments.load();
comments.render();
comments.attachFormHandler();

📦 Dependencies

Server-Side (comments.js, comments-example.js)

• None! Uses built-in Cloudflare APIs and fetch
• Only dependency: Cloudflare Workers runtime

Client-Side (standard.comment.js)

• None! Pure vanilla JavaScript
• Browser support: All modern browsers (ES6+)

Configuration (wrangler.toml)

• Wrangler CLI (local development)
• Node.js 14+ (build environment)

🔐 Security Files

All files follow security best practices:

• ✅ HTML sanitization (comments.js)
• ✅ XSS prevention (standard.comment.js)
• ✅ Email validation (comments.js)
• ✅ Rate limiting support (Cloudflare)
• ✅ Secrets management (wrangler.toml)

📝 Comments in Code

All files include:

• JSDoc function comments
• Inline documentation
• Setup instructions
• Usage examples
• Configuration guides

🎯 Next Steps

1. Choose your setup: COMMENTS-QUICK-START.md or COMMENTS-GUIDE.md
2. Deploy: Follow setup in chosen guide
3. Integrate: Use comments-template.html
4. Test: Submit a comment and verify in GitHub
5. Customize: Adjust spam detection, styling, etc.
6. Monitor: Review moderation queue

📚 Related Files

Standard Framework files that work with comments:

• src/cloudflare/utils.js – Shared utilities
• src/layouts/base.njk – Page templates
• src/styles/standard-98-utilities.scss – Styling utilities

❓ FAQ

Q: What if I want to use a database instead of GitHub?
A: See COMMENTS-GUIDE.md for D1 database alternative pattern

Q: Can I integrate email notifications?
A: Yes! See sendModerationEmail() in comments.js and COMMENTS-GUIDE.md

Q: How do I rate limit?
A: Cloudflare’s built-in rate limiting or KV store pattern in COMMENTS-GUIDE.md

Q: Is this production-ready?
A: Yes! Used in production sites. All files are fully documented and tested.

Q: What’s the cost?
A: Free tier covers most sites. Cloudflare Workers: 100K req/day free

Last Updated: October 22, 2024
Version: 0.10.53
Status: ✅ Production Ready