Overview

Relevant source files

• README.md
• constants.rb

This document provides a high-level introduction to the github-wiki-to-html system, explaining its purpose, architecture, and core concepts. For detailed setup instructions, see Getting Started. For in-depth component documentation, see Architecture and Core Ruby Components.

Purpose and Scope

The github-wiki-to-html system is a static site generator that converts GitHub Wiki content into a deployable HTML website. The system reads Markdown files from a Git-backed wiki repository, processes them through a multi-stage pipeline, and outputs semantically-structured HTML pages suitable for hosting on GitHub Pages or any static web server. README.md1-6

This overview covers:

• The problem domain and solution approach
• High-level system architecture with code-level mappings
• Core processing workflow
• Key files and their responsibilities
• Output structure and deployment model

What is github-wiki-to-html?

github-wiki-to-html is a Ruby-based conversion system that transforms GitHub Wiki repositories into static HTML sites. Unlike dynamic wiki engines that require server-side rendering, this system performs a one-time conversion that generates plain HTML files, making the output fast to serve, easy to cache, and simple to deploy. README.md1-6

The system solves several key problems:

• Preservation: Converts ephemeral wiki content into archival HTML format.
• Performance: Eliminates server-side rendering overhead by pre-generating all pages.
• Portability: Produces self-contained HTML that can be hosted anywhere.
• Customization: Applies custom templates, styling, and metadata to wiki content.
• SEO: Generates structured data, sitemaps, and semantic HTML for search engines.

Sources: README.md1-6

Core Concepts

Static Site Generation

The system operates on a static site generation model:

1. Input: A Git repository containing Markdown wiki files (managed as a directory referenced by INPUT_DIRECTORY). constants.rb10
2. Processing: Ruby scripts read, parse, and transform the content.
3. Output: HTML files written to an output directory (managed as a directory referenced by OUTPUT_DIRECTORY). constants.rb26
4. Deployment: The output directory is pushed to a hosting service (e.g., GitHub Pages).

Git-Based Workflow

The system uses local paths that typically correspond to Git submodules to manage both input and output:

Component	Constant	Path	Purpose
Source Wiki	INPUT_DIRECTORY	source-repo	Input wiki content from GitHub. constants.rb10
Target Site	OUTPUT_DIRECTORY	target-repo	Output static site for deployment. constants.rb26

The Git history in the source repository provides metadata (publication dates, authors, modification history) that enriches the generated HTML pages.

Sources: constants.rb10 constants.rb26

System Architecture

The following diagram maps the system's conceptual architecture to actual code entities and file paths:

System Component Map

Key Architecture Principles:

1. Separation of Concerns: Configuration (constants.rb), logic (github-wiki-to-html.rb), and presentation (template.html.liquid) are separated. constants.rb1-5
2. Declarative Configuration: All site-specific values are defined in constants.rb as Ruby constants. constants.rb7-69
3. Template-Based Rendering: The liquid template engine provides flexibility in page structure without modifying core logic. constants.rb29

Sources: constants.rb1-69 README.md1-6

Data Flow Through Code Entities

This diagram shows how data transforms as it flows through the system's code constructs:

Code Entity Data Flow

Data Transformation Details:

Stage	Input	Processing	Output
Wiki Loading	Markdown files in INPUT_DIRECTORY constants.rb10	Gollum::Wiki initialization	Gollum::Page objects
Metadata Extraction	Git commit history	Git log parsing	Hash with date, author
Template Rendering	HTML + metadata	liquid with template.html.liquid constants.rb29	Final HTML page
Post-Processing	HTML files	js-beautify via shell script	Formatted HTML

Sources: constants.rb1-69

Key Components and Files

The system consists of the following primary files:

File	Purpose	Key Constructs
constants.rb	Centralized configuration constants.	INPUT_DIRECTORY, OUTPUT_DIRECTORY, SITE_URL. constants.rb10-37
template.html.liquid	HTML page structure with placeholders.	Liquid variables for SITE_NAME, PUBLISHER_NAME. constants.rb32-42
github-wiki-to-html.sh	Shell script wrapper for the build process.	Executes Ruby and Node.js tools.

Sources: constants.rb1-69 README.md1-6

Output Structure

The system generates a complete static website in the OUTPUT_DIRECTORY (defaulting to target-repo): constants.rb26

target-repo/
├── index.html                  # Home page (Welcome to Wikinder)
├── <page-slug>.html            # Individual wiki pages
├── sitemap.xml                 # XML sitemap
├── assets/
│   ├── css/
│   │   └── style.css          # Stylesheet <FileRef file-url="https://github.com/wikinder/github-wiki-to-html/blob/27eb8e90/constants.rb#L62-L62" min=62  file-path="constants.rb">Hii</FileRef>
│   ├── js/
│   │   └── mathjax-config.js  # MathJax config <FileRef file-url="https://github.com/wikinder/github-wiki-to-html/blob/27eb8e90/constants.rb#L65-L65" min=65  file-path="constants.rb">Hii</FileRef>
│   └── images/
│       └── icon.jpg           # Site logo <FileRef file-url="https://github.com/wikinder/github-wiki-to-html/blob/27eb8e90/constants.rb#L50-L50" min=50  file-path="constants.rb">Hii</FileRef>

Generated Files:

• index.html: Home page with heading defined by HOME_HEADING. constants.rb53
• sitemap.xml: SEO sitemap for search engines.
• Static Assets: Referenced via constants like STYLESHEET_URL and PUBLISHER_LOGO_URL. constants.rb50-62

Sources: constants.rb26-66