-
Notifications
You must be signed in to change notification settings - Fork 0
User Guide
Installation
Starting a new project
Using Static ⚡
Static ⚡ can be installed via dpkg on Debian-like systems using the deb package provided in the release section.
Alternatively you can clone the repository and place static where you'd need it. There's no need to copy the whole folder to use the tool, skel folder is the one containing the actual tool. If you'd like to install it, follow the next steps:
| Dependencies |
|---|
| Python 3 |
For Debian and derivatives, you can use the deb package. Open your terminal and look for the directory you've placed the package, then run
# dpkg -i static_x.x-x_all.debFor any other Linux, clone the repository and copy the files to a desired location, for instance /opt/static or /home/user/.local/bin.
Issue chmod +x static-init in the location you've copied the tool. Lastly, add the program to PATH variable.
Assuming you installed Static in your distro, or set the path variable to it's location, you can start a new project by issuing static-init <path>
The path argument takes a location to start your new project. This will create a copy of the tool structure into the defined location.
Static projects have the same structure:
| Folder | Function |
|---|---|
| build | Stores the built piece of code from 'pages' |
| dist | Stores the whole site, build and ready to use |
| data | Stores all the media and extra data you'll be using in 'pages' scripts |
| html | Stores two pieces of the HTML, the common info of any page, conveniently the 'header' and the 'footer' of the page |
| pages | Stores all the scripts that will generate the 'changing' part of the pages, each script represents a page |
For the scripts in the root of the project folder:
| Script | Function |
|---|---|
| static | This manages the actions of the tool, it triggers check and build commands |
| stutils.py | This is a helper that stores some functions of the tool, it is not necessary to edit it |
| config.py | This file sets global variables to put into the code of the page modules through the context variable |
The template is a regular HTML file called template.html, it defines a special placeholder {{CONTENT}} to be replaced with page blocks, this is the only file in the html folder. As pointed before, this will be the information repeating at each page. It is allowed to integrate external scripts and styles into the <head> tags as long as you place them into the data folder or you're getting them from a CDN. Static doesn't really care about HTML stuff as long as the files have the default names.
Pages are written as Python modules placed into pages directory, it is necessary to keep __init__.py in the folder.
This scripts will return a formatted text, for convenience all pages scripts must have a function called render() in order to return this text. Formatting is done via variables. An example is explained below.
var = "It works!"
def render(context):
return f'''
<div class="card">
<h1>{var}</h1>
<img src='data/nikola.png' alt='Nikola' />
<p>Now it's time to build new stuff!</p>
<p>Go change the code in pages. Keep it simple and stable, {context["AUTHOR"]}!</p>
</div>
'''Expecting more? I'm sorry to disappoint you. Now you're ready to build your site!
Place yourself in the root of your project and call static build, this will check the structure, generate the page blocks and tailor them together using the pieces of HTML placed in html folder. Once the tool finishes, you can retrieve your site from dist folder. Make sure everything is alright before publishing!