tigsite

Installation

This software has been developed and tested on Linux Debian. It should normally also work on Windows and Macintosh, but hasn't been tested.
Before starting, you need to install PHP (version 8.0 or higher) on your machine.
Some PHP extensions are also necessary ; on debian:

sudo apt install php8.0-yaml

Overview

tigsite
    ├── docs
    ├── config
    |   ├── mysite1
    |   ├── mysite2
    |   └── ...
    ├── src
    └── run-tigsite.php

The tool is run on the command line :

cd tigsite/
php run-tigsite.php <site> <command>

<site> must be the name of a sub-directory of config/.
<command> must be the name of a yaml file inside site's commands/ sub-directory.
For example,

php run-tigsite.php site1 replace-footer

corresponds to this hierarchy :

config/
    └── site1
        ├── commands
        │   └── replace-footer.yml
        └── config.yml

The command name specified does not include the ".yml" extension.

Commands can be organized in subdirectories.
For example,

php run-tigsite.php site1 asides/replace-footer

corresponds to

config/
    └── site1
        ├── commands
        │   └── asides
        │        └── replace-footer.yml
        └── config.yml

Site configuration

Each site managed by this tool must correspond to a sub-directory of config/ and have this structure :

config/
    └── mysite.org
        ├── commands/
        └── config.yml

config.yml

Configuration file containing information used by all commands related to the site.
Example :

site-root: /path/to/the/site/web
exclude:
  - .git
  - .gitignore
  - static

Possible directives are:

Directive	Description		Default
`site-root`	Absolute path to the root directory of the site.	Required
`exclude`	Array of strings containing regular expressions of relative paths to files to exclude from processing (relative to `site-root` defined in config.yml)).	Optional	`[]`

Page configuration

Each html page of a site may contain its own configuration, used by some commands.
Page configuration is a piece of yaml included in a html comment, typically located in the <head> part of the page
This yaml must contain a directive tigsite which contains the configuration directives.

Example :

<head>
    <!-- 
    tigsite:
        sidebar-right: genealogy/sidebar-genealogy.fr.html
    -->
</head>

Command files

When executing the program, the yaml files located in config/<my-site>/commands/ are used to specify :

which php command is used,
the parameters passed to the command.

See below for examples of a command file.
The available php commands are located in src/commands.
In a command file, the unique required directive is command-class
The other directives depend on the command ; they are passed as parameters to the command.

Available commands

insertHtml

Permits to insert html in one or several html page(s).
To work, all concerned pages must have a common fragment of html to mark where the html will be inserted.
The place where the html string should be inserted is marked using either parameter before or after.
The string to insert is specified using either insert-string or insert-file.
The computation of inserted string supports the use of variable substitution.

Parameter	Description		Default
`before`	HTML fragment of the page(s) that will be located before the inserted string (the inserted string will be located after this fragment).	Optional	`null`
`after`	HTML fragment of the page(s) that will be located after the inserted string (the inserted string will be located before this fragment).	Optional	`null`
`insert-string`	String to insert, directly specified in the yaml command file.	Optional	`null`
`insert-file`	Relative path to a file containing the string to insert (relative to site `site-root` defined in config.yml).	Optional	`null`
`exclude`	Array of strings containing regular expressions of relative paths of html files to exclude (relative to site `site-root` defined in config.yml). This list is added to the list built from parameter `exclude` of site configuration, defined in config.yml.	Optional	`[]`

Example of command file:

#
# Command to replace the right sidebar
# Uses the page configuration directive 'sidebar-right'
#

#
# Class of src/commands/ using this config
#
command-class: replaceHtml

#
# Command parameters
#
before: ''
after: ''
# in a html comment of the processed page
replacement-directive: sidebar-right

replaceHtml

Permits to replace existing html in one or several pages.
To work, all concerned pages must have 2 common fragments of html to mark where the html will be replaced.
The place where the html string should be replaced is marked using parameters before and after.
The new string is specified by one of the parameters replacement-string, replacement-file or replacement-directive
The computation of replacement string supports the use of variable substitution.

Parameter	Description		Default
`before`	HTML fragment of the page(s) that will be located before the replacement string (the replacement string will be located after this fragment).	Required
`after`	HTML fragment of the page(s) that will be located after the replacement string (the replacement string will be located before this fragment).	Required
`replacement-string`	Replacement string, directly specified in the yaml command file.	Optional	`null`
`replacement-file`	Relative path to a file containing the replacement string (relative to site `site-root` defined in config.yml).	Optional	`null`
`replacement-directive`	String containing the directive of a page configuration. This directive indicates the path to a file containing the new html code to insert between 'before' and 'after'. Pages that do not contain the specified directive are not processed.	Optional	`null`
`exclude`	Array of strings containing regular expressions of relative paths of html files to exclude (relative to site `site-root` defined in config.yml). This list is added to the list built from parameter `exclude` of site configuration, defined in config.yml.	Optional	`[]`

Example of command file using replacement-directive:

#
# Command to replace the right sidebar
# Uses the page configuration directive 'sidebar-right'
#

#
# Class of src/commands/ using this config
#
command-class: replaceHtml

#
# Command parameters
#
before: '<aside class="sidebar-right">'
after: '</aside>'
replacement-directive: sidebar-right

It permits to have one specific sidebar per page.
Pages containing a page configuration like this are processed:

    <!-- 
    tigsite:
        sidebar-right: astronomy/sidebar-astronomy.html
    -->

Here, the replacement string will be the content of file astronomy/sidebar-astronomy.html.

pagetoc (table of contents)

Permits to compute the table of contents (toc) of one or several html page(s) from a given list of html tags.
For example, the toc of this page was generated from h2 and h3 tags.
This command needs one requirement:
All the html pages that are processed must SHARE A COMMON PIECE OF HTML which permits to indicate WHERE THE TOC MUST BE INSERTED (parameter insert-after or insert-before).

Parameter Type Default Description

action

string

'save'

Describes the action to execute
Can take one of thes values:

`save`	the original file(s) are overwritten with the new toc.
`print-toc`	Prints the new toc without overwriting the original files.
`print-full`	Prints the whole generated page(s) without overwriting the original files.
`list-files`	Prints the files that would be processed by this command.

file string '' Contains the relative path of the file to process.
If not specified, all the html files contained in site-root defined in config.yml are processed (minus files listed in parameter exclude).

exclude Array of
strings [] Contains regular expressions of relative paths of html files to exclude (relative to site site-root defined in config.yml).
This list is added to the list built from parameter exclude of site configuration, defined in config.yml.
If parameter file is specified, this parameter is ignored.

insert-after string null In the resulting page, the toc is inserted after this html fragment of the original page.
Cannot be used if insert-before is used.

insert-before string null In the resulting page, the toc is inserted before this html fragment of the original page.
Cannot be used if insert-after is used.

tags Array of
strings ['h2', 'h3'] The html tags used to build the table of content hierarchy.

create-backup boolean false True if a copy of the original files should be stored in the same directory.
Used only if parameter action = save

backup-extension string '.bck' String appended to the original file name when creating the backup files.
Used only if parameter create-backup = true

toc-css-class string 'pagetoc' CSS class of the div containing the generated toc.

toc-tab-length int 4 Number of white spaces used to indent the pagetoc list.

Variable substitution

Mechanism used by certain commands (insertHtml and replaceHtml) to deal with strings that depend on the currently processed html file.
A special syntax permits to replace strings located between {{ and }} by computed strings.

Currently, the supported strings are:

`{{path-to-root}}`	Relative html path between the file currently processed and the root directory of the site (`site-root` defined in config.yml).