# Usage
## Requirements
Requires the `bs4` python package.
## Installation
To install StartTree for the first time, run the following commands:
(Note: If the `~/.config/StartTree` directory already exists, `init.sh` will not copy the example config to prevent accidentally overwriting a custom config. )
```
git clone https://github.com/Paul-Houser/StartTree.git
cd StartTree
chmod +x init.sh
chmod +x generate.py
./init.sh
./generate.py
```
This will create the directory `~/.config/StartTree` containing the default `config.yaml`, install `starttree.py` to your `$PATH`, as well as generate the html/css, which you can view by pointing your browser at `$HOME/.cache/StartTree/index.html`.
## Config
The config should be placed in `~/.config/StartTree/config.yaml`
## Updating the HTML
To re-generate the html/css after editing the config, execute `starttree.py` from any directory.
# Example Config
```yaml
font_size: 22 # specify font size
theme: void # specify the name of a theme in the themes/ directory, or use 'pywal'
tree_1: # each column should be named 'tree_X' where X is unique for each tree.
general: # Header name
github: "https://www.github.com/" # Link-text: url
gmail: "https://mail.google.com/"
reddit:
# the following is an example of naming a link something with a space,
# or containing characters that cannot be in a yaml variable name.
frontpage:
- "https://www.reddit.com/"
- "front page"
unixporn: "https://www.reddit.com/r/unixporn/"
tree_2:
other:
archwiki:
- "https://archlinux.org/"
- "arch wiki"
hulu: "https://www.hulu.com/"
netflix: "https://www.netflix.com/"
youtube: "https://www.youtube.com/"
```
# Themes
A variety of themes can be found in the `themes` directory.
If one wishes to dynamically theme from `pywal`, they may select `pywal` as their chosen theme in `config.yaml`.
# Docker
In order to circumvent some restrictions on browsers for what is allowed as a "Home" and "New Tab" page, you can host StartTree as a lightweight `NGINX` server through `docker-compose`.
To set this up, one must have `docker` and `docker-compose` installed and configured. Then, go into the directory where you cloned `StartTree`, and run
```bash
cd docker
vim docker-compose.yaml # edit specifics to your liking
docker-compose -f docker-compose.yaml up -d
```
This will make the `NGINX` server persist across reboots. You can point your browser's new tab and home page to `localhost:` and you should see your startpage!
================================================
FILE: config.yaml
================================================
font_size: 22
theme: void
tree_1:
general:
github: "https://www.github.com/"
gmail: "https://mail.google.com/"
reddit:
frontpage:
- "https://www.reddit.com/"
- "front page"
unixporn: "https://www.reddit.com/r/unixporn/"
tree_2:
other:
archwiki:
- "https://archlinux.org/"
- "arch wiki"
hulu: "https://www.hulu.com/"
netflix: "https://www.netflix.com/"
youtube: "https://www.youtube.com/"
================================================
FILE: docker/data/default.conf
================================================
server {
listen 80;
listen [::]:80;
server_name localhost;
#charset koi8-r;
#access_log /var/log/nginx/host.access.log main;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
expires -1;
}
#error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
# proxy the PHP scripts to Apache listening on 127.0.0.1:80
#
#location ~ \.php$ {
# proxy_pass http://127.0.0.1;
#}
# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
#
#location ~ \.php$ {
# root html;
# fastcgi_pass 127.0.0.1:9000;
# fastcgi_index index.php;
# fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name;
# include fastcgi_params;
#}
# deny access to .htaccess files, if Apache's document root
# concurs with nginx's one
#
#location ~ /\.ht {
# deny all;
#}
}
================================================
FILE: docker/docker-compose.yaml
================================================
version: '3'
services:
StartTree:
image: nginx
volumes:
- $HOME/.cache/StartTree/styles/colors.css:/usr/share/nginx/html/styles/colors.css # This needs to be changed depending on theme
- $HOME/.cache/StartTree/index.html:/usr/share/nginx/html/index.html
- $HOME/.cache/StartTree/styles/style.css:/usr/share/nginx/html/styles/style.css
- $HOME/.cache/StartTree/styles/Hack.ttf:/usr/share/nginx/html/styles/Hack.ttf
- $HOME/.cache/StartTree/default.conf:/etc/nginx/conf.d/default.conf # modified conf to disable page caching :)
ports:
- "9876:80"
environment:
- NGINX_PORT=80
restart: unless-stopped
================================================
FILE: generate.py
================================================
#!/bin/python3
import yaml
from os.path import expanduser
from shutil import copyfile
from bs4 import BeautifulSoup
# get home directory
home = expanduser("~")
# get config path
config_dir = home + '/.config/StartTree'
config_path = home + '/.config/StartTree/config.yaml'
# get cache path
cache_dir = home + '/.cache/StartTree'
def prettifyHTML(html):
soup = BeautifulSoup(html, 'html.parser')
prettyHTML = soup.prettify()
return prettyHTML
def parse_yaml():
with open(config_path, mode='r') as file:
file_dict = yaml.full_load(file)
return file_dict
def print_keys(dictionary):
for key in dictionary:
print(key)
if isinstance(dictionary[key], dict):
print_keys(dictionary[key])
def gen_list_indices(html_file, file_dict):
for key in file_dict:
value = file_dict[key]
print(key + "->" + str(value))
if not isinstance(value, list):
html_file.write("
")
def gen_col_headers(html_file, file_dict):
for key in file_dict:
html_file.write("
\n")
html_file.write("
" + key + "
\n")
html_file.write("
\n")
# generate list indices
gen_list_indices(html_file, file_dict[key])
html_file.write("
\n")
html_file.write("
\n")
def gen_columns(html_file, file_dict):
for key in file_dict:
if key.split("_")[0] == "tree":
html_file.write("
\n")
html_file.write("
\n")
html_file.write("
.
\n")
html_file.write("
\n")
# generate the column headers
gen_col_headers(html_file, file_dict[key])
html_file.write("
\n")
html_file.write("
\n")
html_file.write("
\n")
def gen_html(file_dict):
print("Generating index.html...")
# open files
skeleton_html = open(cache_dir + '/skeletons/index.html', 'r')
cache_html = open(cache_dir + '/index.html', 'w+')
# copy skeleton_html to cache_html until Column Start comment
lines = skeleton_html.readlines()
for line in lines:
if line == "\n":
gen_columns(cache_html, file_dict)
else:
cache_html.write(line)
# prettify
cache_html.seek(0)
pretty_string = cache_html.read()
pretty_string = prettifyHTML(pretty_string)
cache_html.close()
cache_html = open(cache_dir + '/index.html', 'w')
cache_html.write(pretty_string)
# close files
skeleton_html.close()
cache_html.close()
print("Done!")
def gen_style(file_dict):
skeleton_style = open(cache_dir + '/skeletons/style.css', 'r')
cache_style = open(cache_dir + '/styles/style.css', 'w')
# find style attributes in file_dict
font_size = 20
theme = "void"
for key in file_dict:
if key == "font_size":
font_size = file_dict[key]
if key == "theme":
theme = file_dict[key]
if theme == "pywal":
theme = home + '/.cache/wal/colors.css'
else:
theme = cache_dir + '/themes/' + theme + '.css'
copyfile(theme, home + '/.cache/StartTree/styles/colors.css')
cache_style.write("@import url('./colors.css');\n")
lines = skeleton_style.readlines()
for line in lines:
if line == "/* font-size */\n":
cache_style.write("font-size: " + str(font_size) + "px;\n")
else:
cache_style.write(line)
def main():
file_dict = parse_yaml()
gen_style(file_dict)
gen_html(file_dict)
if __name__ == '__main__':
main()
================================================
FILE: init.sh
================================================
#!/bin/bash
config_dir=$HOME/.config/StartTree
config_path=$HOME/.config/StartTree/config.yaml
cache_dir=$HOME/.cache/StartTree
# check if .config path exists
if [ ! -d "$HOME/.config" ]; then
echo "The directory '~/.config' does not exist, or you do not have permissions to edit it."
exit
fi
# check if .cache path exists
if [ ! -d "$HOME/.cache" ]; then
echo "The directory '~/.cache' does not exist, or you do not have permissions to edit it."
exit
fi
# check if .local/bin exists
if [ ! -d "$HOME/.local/bin" ]; then
echo "The directory '~/.local/bin' does not exist, or you do not have permissions to edit it."
exit
fi
# check if .config/StartTree exists, create it and config if not
if [ ! -d "$config_dir" ]; then
echo "Creating '~/.config/StartTree'..."
mkdir $config_dir
echo "Copying config.yaml..."
cp ./config.yaml $config_path
echo
fi
# check if config.yaml exists
if [ ! -f "$config_path" ]; then
echo "No config.yaml found in '~/.config/StartTree'"
echo "Copy the example config with:"
echo "\tcp ./config.yaml $HOME/.config/StartTree/config.yaml"
echo "or create your own in that directory."
exit
fi
# create directory structure in .cache
if [ ! -d "$cache_dir" ]; then
echo "Creating '$cache_dir'..."
mkdir $cache_dir
echo "Symlinking themes..."
ln -s $(pwd)/themes $HOME/.cache/StartTree/themes
echo "Symlinking skeleton files..."
ln -s $(pwd)/skeletons $HOME/.cache/StartTree/skeletons
echo "Creating '$cache_dir/styles'..."
mkdir "$cache_dir/styles"
fi
echo "Creating style.css..."
cp "./skeletons/style.css" "$cache_dir/styles/style.css"
echo "Creating Hack.ttf..."
cp "./skeletons/Hack.ttf" "$cache_dir/styles/Hack.ttf"
# add to path
FILEPATH=$(readlink -f "generate.py")
ln -s $FILEPATH $HOME/.local/bin/starttree.py
echo "generate.py has been linked to $HOME/.local/bin/"
echo "Make sure this directory is in your \$PATH"
FILEPATH=$(readlink -f "docker/data/default.conf")
ln -s $FILEPATH $HOME/.cache/StartTree/default.conf
================================================
FILE: skeletons/index.html
================================================
Home
