staticoso docs

View the source for this site: gitlab.com/octtspacc/staticoso-docs

Don't yet mind the fact that there is no CSS at all, and only one single page. Still a heavy WIP :)

Input Files

Note: Non-lowercase file suffixes are currently broken. This will be fixed.

Note: Files with .htm extension are currently broken too.

Templates and Parts

For templates and parts files, formats supported as input are:

HTML (Suffixes: .htm, .html)

Pages and Posts

For pages and posts files, many formats are supported as input:

HTML (Suffixes: .htm, .html)
Markdown (Suffixes: .md, .markdown)
Pug (through pug-cli) (Suffixes: .pug)
Plain text (Suffixes: .txt) (Rendered as plain text enclosed in <pre> tags in the HTML)

Site folder Structure

A full staticoso site folder looks like this:

Assets/: Contains files that will be just copied as they are in the root of the output folder (images, CSS files, ...).
Pages/: Contains website pages.
Posts/: Contains website posts, which differ for some things from pages.
Templates/: Contains base HTML pages to be used as templates for compiling all the pages.
StaticParts/: Contains HTML snippets that can be included statically in HTML templates.
DynamicParts/: Contains HTML snippets that can be included dynamically, via configuration flags, in HTML templates.
Site.ini: Specifies some configuration flags. CLI arguments can often be used as an alternative to this file.

Keep in mind that the only required files (and, consequently, appropriate folders) for a minimum successful build are at least: one HTML base template, and one page or post. Other elements are optional.
A reasonably minimal staticoso site folder tree can look like this:


.
├── Assets
│   ├── Default.css
│   └── favicon.ico
├── Templates
│   └── Default.html
├── Pages
│   └── index.md
└── Posts
    └── 2022-05-16-That-Day.md

Preprocessor Flags

Preprocessor flags can be included in single-line comments.
They must be prepended by a % (percent sign) character, and values are assigned with the standard Python INI syntax.

Note: Markdown doesn't officially support comments. staticoso thus uses its own syntax: a line starting with // (2 slashes) indicates a comment.

For example: // % Flag = Value

Supported values:

Template
Style
Type
Index
Feed
Title
HTMLTitle
Description
Image
Macros
Categories
CreatedOn
EditedOn
Order

TODO: Finish writing this

Configuration Flags

Many configuration flags are available.

They can be specified from the Site.ini file, under the relative sections, or as command-line arguments.
CLI arguments, if specified, always take priority over the INI values; this is to easily allow for many different build workflows on the same site.

In the INI file, flags are specified as they are, separated by new lines.
As CLI arguments, they are prepended by double dashes (--) and section name, and values are assigned to them with your standard shell syntax (usually, it will be --SectionFlag="Value", with a space for separation between arguments).

Note: Some flags are currently CLI-only, while others are file-only. This will be soon fixed.

Site

Name (--SiteName): The name of your site.
BlogName (--BlogName): The name of the blog section of your site. Can be omitted, and the site name will be used instead.
Tagline (--SiteTagline): The tagline or motto of your site.

Minify

Minify (--Minify): Whether or not to minify the output HTML. Defaults to False.
KeepComments (--MinifyKeepComments): Optionally keeping comments in minified HTML, instead of removing them. Defaults to False.

Internal Markup Tags

Note: You only really need to care about this section if you're developing themes. If you are building your site with an already prepared theme, then you can do without this information.

staticoso uses a simple internal markup language that's the essence of its template system.

Tags are enclosed in square brackets (with colons as token separators), and declared with the form [staticoso:Name:Values].
For some tags, there are no values to be specified, so the last part can be omitted. Starting the declaration with staticoso is always required.

You can use the following tags in your templates or pages, to let everything work as you want. Some are obviously needed for compiling minimum viable pages, like the one for displaying content.