wg

A static website generator written in Fennel.

Table of Contents

• Document conventions
• Requirements
• Quick start
• Installation
  • Downloading wg
    • To download wg
  • Compiling wg
    • To compile wg
  • Installing wg globally
    • To install wg globally
  • Installing wg locally
    • To install wg locally
  • Installing wg to a custom location
    • To install wg to a custom location
• Uninstallation
  • Uninstalling wg globally
    • To uninstall wg globally
  • Uninstalling wg locally
    • To uninstall wg locally
  • Uninstalling wg from a custom location
    • To uninstall wg from a custom location
• Commands
• Usage
• Default files and directories explained
  • The layout directory
    • The header file
    • The footer file
  • The convert directory
  • The copy directory
  • The build directory

Document conventions

• Note: Notes signify additional information.
• Tip: Tips signify an alternative procedure for completing a step.
• Warning: Warnings signify that damage, such as data loss, may occur.
• Example: Examples provide a reference of how a procedure would be performed in the real world.
• Inline code: Inline code signifies package names, filenames, or commands.
• Code block: Code blocks signify file contents.

Requirements

• Python3 - To use Python3's simple HTTP server.
• Fennel - To compile the program into a single Lua script.
• Lua5.3 - To run the compiled Lua script.

Note: The fennel binary or script should be in a directory on your $PATH.

Quick start

1. Ensure Lua5.3 is installed.
2. Download the wg.lua file using one of the following commands:
   • curl https://git.m455.casa/m455/wg/raw/branch/main/wg.lua -o wg
   • wget https://git.m455.casa/m455/wg/raw/branch/main/wg.lua -O wg
3. Move the wg to a directory on your $PATH.
4. Run wg help.

Installation

This section will guide you through downloading and installing wg either globally or locally.

This section consists of the following subsections:

• Downloading wg
• Compiling wg
• Installing wg globally
• Installing wg locally

Downloading wg

This section will guide you through downloading wg using git.

To download wg

1. git clone https://git.m455.casa/m455/wg

Compiling wg

This section will guide you through compiling the files that make up wg into a single Lua script.

To compile wg

1. make compile

Installing wg globally

This section will guide you through installing wg globally. This method will install wg into /usr/local/bin, which requires you to have root access to your machine.

Tip: If you don't have root access to your machine, check out the Installing wg locally section.

To install wg globally

1. cd wg
2. sudo make install

Installing wg locally

This section will guide you through installing wg locally. This method will install wg into ~/.local/bin.

To install wg locally

1. cd wg
2. make install-local

Installing wg to a custom location

This section will guide you through installing wg to a custom location.

To install wg to a custom location

1. cd wg
2. make DESTDIR=~/path/to/custom/location install

Note: If you choose to install wg to a custom location, you will need to remember where you installed wg if you decide to uninstall it later.

Uninstallation

This section will guide you through uninstalling wg either globally or locally.

This section consists of the following subsections:

• Uninstalling wg globally
• Uninstalling wg locally
• Uninstalling wg from a custom location

Uninstalling wg globally

This section will guide you through uninstalling wg globally. This method will remove wg from /usr/local/bin, which requires you to have root access to your machine.

To uninstall wg globally

1. cd wg
2. make uninstall

Uninstalling wg locally

This section will guide you through uninstalling wg locally. This method will remove wg from ~/.local/bin.

To uninstall wg locally

1. cd wg
2. make uninstall-local

Uninstalling wg from a custom location

This section will guide you through uninstalling wg from a custom location.

To uninstall wg from a custom location

1. cd wg
2. make DESTDIR=~/path/to/custom/location uninstall

Commands

• init - Creates required directories and files in the current directory.
• build
  • Recursively copies directories and files from the copy/ directory into the build/ directory.
  • Recursively converts Markdown files in the convert/ directory to HTML files in the build/ directory.
• serve - Serves files in the 'build/' directory on port 8000, allowing you to see how your website will look locally before it goes live.
• clean - Deletes all contents of the 'build/' directory.
• help - Displays the help message.

Usage

• wg init
• wg build
• wg serve
• wg clean
• wg help

Default files and directories explained

This section explains each of the default files and directories that are created after running wg init.

The layout directory

• The layout directory must contain a header.md file and footer.md file.

The header file

The contents in the header.md file will be used as a header for any HTML files that were generated from the convert directory.

The footer file

The contents in the footer.md file will be used as a footer for any HTML files that were generated from the convert directory.

The convert directory

• The convert directory must contain an index.md file.
• The index.md can be empty.
• The index.md file will be used as the landing page.
• The convert directory should only contain directories, and Markdown files ending in .md.
• The directory structure in the convert directory will be mimicked in the build directory.
• Empty directories will not be copied to the build directory.
• Markdown files will be converted to HTML and moved into the build directory.
• Markdown files contain a header and footer, which can both be customized by editing layout/header.md and layout/footer.md.

The copy directory

• The copy directory must contain a style.css file.
• The style.css can be empty.
• The style.css will be linked to from any HTML files that were generated from the convert directory.
• The copy directory can contain any files or directories.
• The directory structure in the copy directory will be mimicked in the build directory.
• Empty directories will not be copied to the build directory.

The build directory

• The build directory is used by the build command.
• The build directory contains the generated website.
• The build directory contains HTML files that were either generated from Markdown files from the convert directory, or copied from the copy directory.
• The build directory contains the directory structures from the convert and copy directories, and the style.css file from the copy directory.

Note: This is the directory you will want to use as your website.