This document provides a high-level overview of the github-wiki-to-html system, explaining its purpose, architecture, and core components. It covers the conversion pipeline from GitHub Wiki markdown to static HTML, the technology stack, and how the various system components interact.
For detailed setup instructions, see Getting Started. For in-depth architectural details, see Architecture. For component-specific documentation, refer to Ruby Components and Node.js Components.
Sources: README.md1-6 constants.rb1-69 .gitmodules1-7
The github-wiki-to-html system converts GitHub Wiki repositories into self-hosted static HTML websites. It transforms wiki content authored in GitHub Flavored Markdown (GFM) into a complete static site with SEO optimization, structured metadata, and professional formatting.
The system is designed for users who want to:
Sources: README.md1-6 constants.rb31-68
The system operates as a multi-stage transformation pipeline that reads wiki content from a Git submodule, processes it through Ruby and Node.js tools, and outputs a complete static site to another Git submodule.
Diagram: Core System Components
The architecture consists of three layers:
| Layer | Components | Purpose |
|---|---|---|
| Input | source-wiki/ submodule | Cloned GitHub Wiki content |
| Processing | Ruby scripts (github-wiki-to-html.rb, methods.rb, constants.rb, gollum-config.rb) | Content transformation and HTML generation |
| Post-Processing | js-beautify via Node.js | HTML/XML formatting |
| Output | target-site/ submodule | Generated static site for deployment |
| Orchestration | github-wiki-to-html.sh | Coordinates Ruby and Node.js execution |
Sources: .gitmodules1-7 constants.rb10-29 README.md1-6
The system integrates multiple technologies into a cohesive pipeline:
Diagram: Technology Stack Dependencies
Sources: Gemfile Gemfile.lock package.json package-lock.json
The project uses Git submodules to separate source content, build logic, and published output:
| Path | Type | Purpose | Repository |
|---|---|---|---|
source-wiki/ | Git submodule (HTTPS) | Input: GitHub Wiki markdown files | wikinder/wikinder.wiki |
target-site/ | Git submodule (SSH) | Output: Generated static site | wikinder/wikinder.github.io |
| Root directory | Main repository | Build logic and configuration | wikinder/github-wiki-to-html |
Sources: .gitmodules1-7 constants.rb10-26
The conversion process follows a linear pipeline with distinct stages:
Diagram: End-to-End Data Flow with Code Entity Names
This diagram maps the conceptual stages to actual code entities:
| Stage | Code Entity | Location |
|---|---|---|
| Initialize Wiki | Gollum::Wiki.new | github-wiki-to-html.rb |
| Iterate Pages | wiki.pages | github-wiki-to-html.rb |
| Parse Markdown | Commonmarker.to_html | github-wiki-to-html.rb |
| Post-process | postprocess_html | methods.rb |
| Render Template | Liquid::Template.parse | github-wiki-to-html.rb |
| Generate Home | generate_html_file | methods.rb |
| Generate Sitemap | generate_sitemap_file | methods.rb |
Sources: github-wiki-to-html.rb methods.rb gollum-config.rb
The Ruby layer handles all content transformation and HTML generation:
| Component | File | Purpose |
|---|---|---|
| Main Orchestrator | github-wiki-to-html.rb | Coordinates the entire conversion process |
| Configuration | constants.rb | Site URLs, paths, branding, asset locations |
| Engine Config | gollum-config.rb | Gollum and Commonmarker settings |
| HTML Utilities | methods.rb | Functions for HTML generation, sitemap, post-processing |
| Page Template | template.html.liquid | HTML structure with Liquid variables |
Sources: github-wiki-to-html.rb constants.rb1-69 gollum-config.rb methods.rb template.html.liquid
The system configuration is distributed across multiple files:
Diagram: Configuration System Structure
Sources: constants.rb1-69 gollum-config.rb .jsbeautifyrc
| Constant | Value/Purpose | Line Reference |
|---|---|---|
WIKI_REPO | Pathname('source-wiki') | constants.rb10 |
OUTPUT_DIRECTORY | Pathname('target-site') | constants.rb26 |
SITE_NAME | 'Wikinder' | constants.rb32 |
SITE_URL | URI('https://wikinder.org') | constants.rb37 |
HOME_URL | Pathname('/') | constants.rb56 |
HTML_TEMPLATE_FILE | Pathname('template.html.liquid') | constants.rb29 |
STYLESHEET_URL | '/assets/css/style.css' | constants.rb62 |
LICENSE_URL | 'https://creativecommons.org/licenses/by-sa/4.0/' | constants.rb59 |
Sources: constants.rb10-68
Each wiki page's Git history is analyzed to extract publication metadata:
Diagram: Git History Metadata Extraction
The system extracts:
versions.last)versions.first)Sources: github-wiki-to-html.rb
The postprocess_html function in methods.rb performs link normalization:
| Transformation | Purpose |
|---|---|
Strip .md extensions | Convert wiki-style links to web-friendly URLs |
| Adjust internal links | Ensure proper routing within the static site |
| Preserve external links | Leave absolute URLs unchanged |
Sources: methods.rb
The system uses Git submodules to maintain separation between source and output:
Diagram: Submodule Data Flow
The workflow pattern:
git submodule update --remote source-wiki pulls latest wiki content./github-wiki-to-html.sh generates static sitetarget-site/ to trigger GitHub Pages deploymentSources: .gitmodules1-7 github-wiki-to-html.sh
The system provides two execution methods:
| Method | Entry Point | Use Case |
|---|---|---|
| Shell Script | ./github-wiki-to-html.sh | Manual execution, direct system access |
| Docker | docker build + docker run | Isolated environment, CI/CD integration |
Both methods execute the same Ruby processing followed by Node.js beautification.
Sources: github-wiki-to-html.sh Dockerfile
The generated static site in target-site/ has the following structure:
target-site/
├── index.html # Home page with article listing
├── [page-slug].html # Individual article pages
├── sitemap.xml # SEO sitemap
└── assets/ # CSS, JavaScript, images (external)
Each HTML file includes:
Sources: github-wiki-to-html.rb methods.rb template.html.liquid
This wiki is featured in the repository
Refresh this wiki