How To

Add automatically an image to a page

Simply put a file with the same name, but different extension (jpg versus txt) in the same directory.

Create a new configuration file or adding options

It can be resetted, or you can have to add a new option or rebuild one cancelled with defaults: run --createconf fullpathofdirectory

Create a new site

Run the application with these parameters: --newsite directoryname

Build a php file

Insert, in the first rows of file txt, a row like

:> filename:name-of-the-file.php

Change a css style

Under the /site/ directory, you can find style.css. style.css is always created, but you modify it, still adding classes and modifying tags rules.

Changing a title of a page

To change page title, without regarding file name, you can add a :> title:mytitle part at the beginning of the file. This can contain the normal syntax for multilingual pages (and obviously must contain it if page is multilingual). Titles that are all lower will be capitalized, others will be leaved as they are.

Comments systems

There are some comments systems available, but I can speak only about Disqus, also if others should be similar as use. To use it, I've created a disqus file in /site/vars, copied from Disqus example.

<div id="disqus_thread"></div>
var disqus_shortname = 'XXXXXXX';
var disqus_identifier = 'ygzuvrjplxpf-how-to';
var disqus_developer = 0; // developer mode is on, 0 is off
  (function() {
    var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
    dsq.src = 'http://' + disqus_shortname + '';
    (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
<noscript>Please enable JavaScript to view the <a href=''>
    comments powered by Disqus.</a></noscript>

"XXXXXX" is the name of the site yoùll register with Disqus. Then, in the template for the pages that you will post (I've done a template in /site/tmpl, and then symlinked to it a file template in all /posts/year directories) you need to add a ${disqus} before </body> line. Correct content is defined py ${pathid} template instruction.

There are also other way to use comments: for example, if you don't like to save your data on Disqus servers (and you don't want to make Disqus or IntenseDebate knowing your visitors tracking), you can use Staticman: this simple mode allow you to save data on you Github, and still can apply moderation.

Correct errors that are always present in a text file

For example, you can use some incorrect words, or a bad indentation. You can use a filepreprocessor line in the action file, in the format of the Python templates, like

filepreprocessor /usr/bin/application "${file}"
where application will correct the text. Application can be also a bash script, but, in all cases, remember to define the full path when using gstatic with cron.

Escaping some chars

In some cases, application can process some characters as keywords, and you don't want it. For chars "{}$%<>_*#[]/", you can avoid this putting a slash before.

Forums on a static site.

Look at Muut. This is an embeddable way to have personal forums on your site.

Make a line of text not followed by a <BR>

When a line ends in the text file, processing will be followed by a <BR> tag. Adding 4 spaces at the beginning of the line will avoid this addiction.

Modify a template

Basically, a template is an html file, with some parts that can be changed by function results. For example, you can take an html, replace all contents into the BODY tag, then insert a word ${body} (uppercase and the 2 percent). This will be replaced with the content of the text file going to be compiled. Politics for use of templates are explained here

New image gallery

Look at the directory where galleries are builded, if not changed is images. Then, create a directory in it and put jpg images in the same. They will be resized with the defaults or the ovverrider settings passed to application with action file, the command used is setimageswidth. Galleries can be more than one, with the directory structure home/gallerieshome/gallery, where gallerieshome can be set via actions script one than more time.

Put page images in graphs links

There are some template strings that are done for this. you'll put in page templates strings like this

<meta name="twitter:image" content="${sitename}/${pagepath}/${pagename}.jpg">

and you'll get correct image link in the final page.

Set access control to a directory

First you must create a file (default name is "", but you can set it with setpasswdfile in the action file). In this file, you should put, one for row, the user, a ":" char, and the password, like "user:password". Inserting a row in the action file starting with securityopt (like securityopt dirname), the directory will be parsed for the password file, and the .htaccess and .htpasswd will be created. Upload them to the site, and check how they work before relying to them. Note than password encryption, in the Apache standard way, needs the presence of openssl executable in the path, and that the passwords will be truncated to 8 chars. You probably need also to insert a row with setsitepath parameter in the action file, if your server is hosted by a provider.

Set last post as new home page with .htaccess file

You should create a file with the name you like, in the root dir of the site, and make it doing a new .htaccess file. In the next example, I've put an example from my site, containing also error pages url modifications.

:> date:20140322
:> uid:index.html
:> filename:.htaccess
:> tmpl:firstpage
  ErrorDocument 403
  ErrorDocument 404
  Redirect 307 /index.html${lastpost}

Files will be produced with the template called firstpage, that is simply containing instructions to insert body content of this file (ie the previous processed content)


Simply producing of files in html 4.01 mode

Simplest way is to use a file postprocessor like Tidy, that will analyze produced html to standardize output. An example line to add in action file to do this, can be

filepostprocessor /usr/bin/tidy -u -c -i -utf8 -q -m "${file}"

Upgrade the site with new files via ftp

Simplest way is using a program that can do the works synchronizing all. For example, you can use the script that is simple to find on the net, while I'm using lftp, a ftp program that is distribuited with all major distros. Simply I've done a script and put it in the crontab. This is the example script, that includes site synchronization, deleting of files that aren't present in the local directory, and excluding mydir directory from works.

# a part using lftp
lftp -f "
open $HOST
user $USER $PASS
mirror --reverse --delete --verbose --use-cache --only-newer --exclude-glob mydir/ $SOURCEFOLDER $TARGETFOLDER
exit 0

Lftp can do many other things, and can be tuned to use more options, like parallel processes or speed. Another way to set site updated, is to mount remote filesystem with curlftps and synchronize relative directory.

Writing a multilingual site

1) Set a row with desidered languages in configuration file, for example setlanguages en|it|de Languages that are usable should be all these that have a two chars name, like "en", "de", "it", etc etc... in my linuxbox, for example, I got the line LANG=it_IT.UTF-8, and the first two is considered to be the language.

where first is the default language. 2) Set titles via format way at the beginning of the file, like

:> title:en Bread|it Pane|de Broth
with the first two chars showing language and others for title. Parts are divided by a pipe. 3) Divide the texts in files in this way:

  Text in english
  Testo in italiano

This will be showed in generated file. Yoùve to add ${scriptlang} in the template, to get page in a language compatible with browser settings. The browser must use Javascript.

Writing escaped words or templating into a code block

There many tricks to do this and keep it automatically updated without errors, and using Markdown feature of the tab at the beginning of the row carries us to strange behaviours, but the simplest, at least for me, is to have a replace block for selection. An example: I want to write ${listifiles} in a code block.
Add two file, in directory /site/var, called cbstart e cbend. Set the content of first file to <pre><code> and **</code></pre> in the second. Add, at the beginning of the block we want to create, ${cbstart}, and, at the end of block, ${cbend}. Insert escaped sequences into block.
Block will be formatted like Markdown tabbed rows, but it will contains correctly escaped sequences.

Last update: 2020-09-06 12:11