Flock SSG | Usage Documentation

# FLOCK

HOME DOWNLOAD INSTALLATION HOW TO USE PROCESS TEAM USEFUL LINKS

# FLOCK SSG

Welcome to Flock SSG, the static site generator with self-migrating links.

## What is Flock?

Flock is a simple command-line tool, written in Python, to generate websites. The program gathers information on how the website should look like from the user. The information is provided in the form of plain-text, formatted in Markdown. This information includes, theme, colors, data/text to display. The user inputs the path to a folder with one or more markdown files (file.md) to the website generator. The program then takes these files, indexes them and converts them to working HTML to then save them to a new location, choosen by the user. This folder contains the correct hierarchy for the website to function and it's ready to be uploaded on any hosting service.

## Installation

First of all, you need python installed on your machine to run Flock. If you're on Linux or Mac, you probably already have python installed. If you are on Windows, here's a guide on how to install python: Install Python on Windows. Also make sure you have the "pip" python library installed.
Then, you can download the latest version of Flock from here: Flock Releases.
Open the terminal for you OS of choice, change your working directory to the one of the installer you just downloaded (cd [PATH_TO_FOLDER]) and run the installer script (sh install_flock.sh).
If everything went well you should be all set. You can now Flock by typing python -m Flock.flock in your command line.

## How To Use

Before you can use Flock, you need to make sure you have all of your files and data you wanna turn into a website setup correctly. Here's a list of requirements for your website folder:

- All text files must be written in Markdown
The extension of a Markdown file is .md
Here's a reference on how to write in Markdown: Markdown Cheat Sheet
- All file and folder names should not contain any spaces.
- All file names need to contain a unique file identifier
That is a name or code that will be used to keep track of your file. This should be added at the end of your file name, following a -.
Here's an example of what a file name should look like: Page_of_my_website-PG01.md.
This should be applied to all files, including images and other assets, since it is important to link your files with each other in your website.
- The main website page unique file identifier must be index. The filename can anything else as long as the file identifier satisfies this requirement.
- All local files you want to include in your website should be in the same local folder, subdirectories are allowed.
- You can save your website folder wherever you want on your computer, Flock will be able to find it

When you run Flock, it will need only three things from the user:

- The name of the folder containing the markdown files (aka: the website to convert)
Flock only needs the name of the folder, it will be able to search and find where that folder is on its own. However, if you wanna make the search easier, make sure that name is unique in your filesystem (perhaps you can add FLOCK- to the beginning of the folder name).
- The name of the folder where you want to save the website
(The same conditions os the first folder name apply here)
- The number of the theme to choose when prompted for it
You can also choose to provide your own stylesheet to have more control over the look of your website. Just select the correct option and give Flock the full path of where that is saved.

Here are some extra useful features that you could use:

- To run Flock in verbose mode, meaning it will print out exactly what it is doing on the console, type -verbose at the time of execution
- To get this guide to show whe you run Flock, type -help at execution
- All assets and information, including log files of every execution, can be found in the folder ~/.flock_preferences/logs/ under the user home-folder

## Team

Flock development team members:

- Derek Connelly - @CONNELD
- Ricky Dall'Armellina - @rdall96
- Dan Levy - @Reinok
- Lukas Mallory - @lukeylad19

## Useful Links

Github Project Page: Flock SSG
Markdown Python Library: Markdown Library
Video Presentations: Flock Team on Youtube
Example Websites: Templates