How to Deploy & Use mhinz/vim-galore

# Vim-Galore Deployment & Usage Guide

A comprehensive guide for deploying and using the vim-galore documentation repository locally or within your organization.

## Prerequisites

- **Git** (2.0+) for cloning the repository
- **Vim** (8.0+ recommended) to practice examples and generate HTML output
- **Web browser** (Chrome, Firefox, Safari, or Edge) for reading HTML exports
- **Optional**: Static site generator (Jekyll, Hugo) if hosting as a documentation site

## Installation

### Clone the Repository

```bash
git clone https://github.com/mhinz/vim-galore.git
cd vim-galore

Verify Content Structure

ls -la
# Expected: README.md, PLUGINS.md, static/, and translation references

Access Translations (Optional)

The repository references community translations. Access them via the linked repositories:

Chinese: https://github.com/wsdjeg/vim-galore-zh_cn
Japanese: http://postd.cc/?s=vim-galore
Portuguese: https://github.com/lsrdg/vim-galore
Russian: http://givi.olnd.ru/vim-galore/vim-galore-ru.html
Vietnamese: https://github.com/kyoz/vim-galore-vi

Configuration

Minimal Vim Configuration for Practice

Create a temporary vimrc to follow along with the guide's examples without affecting your main configuration:

vim -u NONE -N -c "set nocp"  # Start Vim without vimrc but with nocompatible mode

Or use the minimal vimrc approach referenced in the documentation:

" minimal-vimrc
set nocompatible
filetype plugin indent on
syntax on
set hidden
set wildmenu
set showcmd
set hlsearch
set incsearch
set backspace=indent,eol,start
set autoindent
set nostartofline
set ruler
set laststatus=2
set confirm
set visualbell
set t_vb=
set mouse=a
set cmdheight=2
set number
set shiftwidth=4
set softtabstop=4
set expandtab

Environment for HTML Generation

Ensure your Vim installation has the +syntax feature enabled:

vim --version | grep +syntax

Build & Run

Local Reading

Option 1: Direct Markdown Reading

# Using Vim
vim README.md

# Using less with markdown rendering
less README.md

Option 2: Generate HTML from Buffer As documented in the "Generating HTML from buffer" section:

Open the file in Vim:
```
vim README.md
```
Convert to HTML:
```
:TOhtml
```
Save the generated HTML:
```
:w vim-galore.html
```

Open in browser:

xdg-open vim-galore.html  # Linux
open vim-galore.html      # macOS
start vim-galore.html     # Windows

Full Site Generation

To serve as a static documentation site:

# Using Python's built-in server (for local testing)
python3 -m http.server 8000

# Using Node.js http-server
npx http-server -p 8000

# Access at http://localhost:8000/README.md

Deployment

GitHub Pages (Recommended)

Since this is a documentation repository, deploy via GitHub Pages:

Push repository to GitHub
Navigate to Settings > Pages
Select source branch (usually main or master)
Access at https://yourusername.github.io/vim-galore/

Internal Documentation Server

For organizational deployment:

Using Nginx:

server {
    listen 80;
    server_name docs.company.internal;
    root /var/www/vim-galore;
    index README.md;
    
    location ~ \.md$ {
        add_header Content-Type text/plain;
    }
}

Using Docker:

FROM nginx:alpine
COPY . /usr/share/nginx/html
EXPOSE 80

Build and run:

docker build -t vim-galore-docs .
docker run -d -p 8080:80 vim-galore-docs

PDF Generation

For offline distribution:

# Using pandoc
pandoc README.md -o vim-galore.pdf --pdf-engine=xelatex

# Using Vim's hardcopy feature
vim README.md -c "hardcopy > vim-galore.ps" -c quit
ps2pdf vim-galore.ps

Troubleshooting

Encoding Issues with Special Characters

Problem: Vim special characters (like <C-a>) display incorrectly in browser.

Solution: Ensure UTF-8 encoding when generating HTML:

:set encoding=utf-8
:TOhtml

Broken Internal Links

Problem: Relative links (e.g., #intro-1) don't work when viewing raw markdown locally.

Solution: Use a markdown viewer that supports anchor links, or convert to HTML using :TOhtml which preserves anchor functionality.

Large File Performance

Problem: Slow scrolling in README.md due to syntax highlighting.

Solution: Disable syntax highlighting for large files:

:setlocal syntax=off
" Or use folds
:set foldmethod=marker

Clipboard Integration Testing

If testing clipboard examples from the "Clipboard" section:

Linux/BSD: Ensure xclip or xsel is installed:

sudo apt-get install xclip  # Debian/Ubuntu
sudo pacman -S xclip        # Arch

macOS: No additional packages needed, but ensure Vim is compiled with +clipboard:

vim --version | grep clipboard

Translation Link Rot

Problem: External translation links return 404.

Solution: Translations are community-maintained. Check the main repository's issue tracker for updated links or use browser translation features on the original English documentation.

License Note: This documentation is licensed under CC BY-SA 4.0. When deploying internally or publicly, ensure attribution to Marco Hinz and link back to the original repository.