Skip to content

Latest commit

 

History

History
166 lines (110 loc) · 6.99 KB

README.md

File metadata and controls

166 lines (110 loc) · 6.99 KB
Raw

SiteSync

SiteSync is my flexible static-site generator. The script can do the following:

  • Initialize a website directory with the minimum amount of files and structure that the script needs to run the "build" command
  • Generate a local, "testing" version of the website where you can make and view changes before making it live
  • Generate a public version of the site, which can be mirrored to where it is served from with a user-configured deploy command

Dependencies

Sitesync uses the GNU Coreutils found on most Linux systems; the following programs need to be installed as well:

  • A text editor
  • Rsync
  • Perl
  • A Markdown processor that can create non-standalone documents, without HTML headers or footers (if the user wants Markdown -> HTML conversion). These are some options that work:
    • Lowdown
    • Pandoc
  • Git or OpenSSH (to deploy the website)

Install

  1. Install this script by cloning this repository

git clone this_page's_url

  1. cd into the cloned repository directory

cd sitesync

  1. Install the script with make

make install

The script installs at .local/bin/, and the manual installs at .local/share/man/man1/sitesync.1

Access the manual page with man sitesync

Commands

SiteSync uses the following syntax:

sitesync [OPTION] [DIRECTORY]

Options

These are SiteSync's available options:

init

init : Creates a new website directory, with the minimal structure and files necessary for the build option to work

build

build : Performs the following actions to build a local version of the website:

  • Syncs html files from the content/ directory in the local/ directory
  • Converts Markdown files in the content/ directory into html files in the local/ directory
  • Builds a blog page with links to any files stored in the /content/blog/ directory (blog.html is the default blog file)
  • Wraps all html files in the template stored in the assets/template.html file
  • Creates links to the root directory by replacing the {{ root }} template placeholder with the proper link back to the website root
  • Generates a sitemap.xml file and stores it in assets/sitemap.xml
  • Copies all non-html files from the assets/ directory to the local/ directory

After running the build command, the user can open their website in their web browser at file:///absolute/path/to/website/local/index.html

You may also run a local server to the website with Python's built-in server command:

python3 -m http.server 3000 --directory example/local/

example/local represents the path to your website's local/ directory

deploy

deploy : performs the same website build process as build with the public/ directory as the target, and deploys the website with the user configurable deploy command, defined in the website config file stored at $XDG_CONFIG_HOME/sitesync/ (the config file has the same name as the website directory)

User-configurable deploy command

Configure a website's deploy command by editing the deploy function stored in the $XDG_CONFIG_HOME/sitesync/ config file. A website directory with the name example/ will have a config file stored at $XDG_CONFIG_HOME/sitesync/example.

The deploy command doesn't deploy the website to anywhere until the user defines the command.

There are a few options the user can consider when configuring their deploy command:

Sync website to a server with rsync

You can sync the public/ directory to a server using SiteSync's built in variables with the following command.

deploy() {
	rsync -az --delete "$site_dir"/public/ user@"$website":path/to/server/website/directory/
}
Push the site to a Git repository

If you'd like to serve the website through a git repository that deploys a website through Github Pages, GitLab pages, or Netlify you can do something similar to the following:

deploy() {
	git add -A #stage all new and updated files
	git commit -m "generic commit message" #commit all files
	git push #push files to git and trigger deployment
}

Website directory structure

This is the basic directory structure that SiteSync creates with the init command, along with a config file saved in $XDG_CONFIG_HOME/sitesync (SiteSync creates this directory if it doesn't exist already).

example/
├── assets
│   ├── styles.css
│   └── template.html
├── content
│   ├── blog
│   │   └── 2021-12-30_An_example_post.md
│   ├── blog.html
│   └── index.md
├── local/
└── public/

The config directory is structured like this, with a config file for each website that's been initialized with the init command:

$XDG_CONFIG_HOME/sitesync/
├── example
└── another_example_website

Template file

Sitesync uses the assets/template.html file to define the HTML header and footer for the website. The template should have the header, nav menu, footer, and any other content that the user wants on every page of their site.

These are the file template options:

Option Purpose
{{ root }} Used for file paths that should lead to the root of the website after Sitesync runs. This exists for subdirectories like blog/ that need the nav menu links to be ../page-name.html to point to the pages in the website's root directory.
{{ title }} The title for each page uses each page's first

{{ content }} Used as the placeholder for the content from each page in the content/ directory

Compatibility

OS Compatibility
Linux Works
Windows Works through Windows Subsystem for Linux (WSL)
MacOS Needs GNU Sed installed, and all instances of sed in the script substituted with gsed
*BSD Probably needs a different Sed implementation, similar to MacOS