ASWSG - Another|Alexanders Static WebSite Generator

ASWSG allows you to generate Websites using Markup Syntax and HTML.

• make friendly - to be integrated in your workflow
• configurable syntax - to match different markup dialects

It is build with the idea of classical UNIX tools to do one job. ASWSG behaves just like a compiler parsing a Markup file and generating a new HTML output. ASWSG will not generate a filesystem structure, or an HTML frame, but you can do so using includes and use it with a build system like make.

HTML and Markup can be mixed, reusable includes may be used for headers, footers and other repeating code blocks. Most benefits come from using dynamic variables, which are partly set dynamically by aswsg, by the document or via the command line and the include system. In example the current date, time and the actual filename is set dynamically, author, creation date and others in the document, the sitename as a command line parameter. But it is even possible to redefine markup symbols due to different markup dialects. (i.E. use "!" instead/as well of "=" for headers.) All variables can be used subsequent, also in included files. (i.E. using the article name in a header include.)

This tool will generate new HTML code, which -- of course -- may contain dynamic code.

Note: This is under development, but what's not.

Why should I use it

You like to create websites, and you want to have the freedom to build and use html the way you like it using your favorite tool chain. You are not forced to use a specific framework or project structure.

Features

Released

• Simple markup parsing
  • line based
    • headers
    • paragraphs
    • ordered and unordered lists
    • cites
    • raw lines
    • tables
    • comments
  • inline based
    • bold
    • emphasised
    • strike trough
    • underline
    • links
      • link type [[name|link]] (without rel=external)
      • link type [name](link) (for external links with rel="external")
        • support link relationship attribute "external", see https://www.w3schools.com/tags/att_a_rel.asp
      • link type [[URL]] with link-index
      • link type => URL description - a gemini style link
    • block based
      • quotes
      • preformatted (code)
      • raw html
      • comments
• include files
  • include list of files by pattern
• Setting and using of variables
  • Setting variables (in this order, later overwrites former)
    1. static defaults
    2. dynamically like filename
    3. from command line parameter
    4. in parsed file
  • Using variables everywhere, also in commands, but not in raw imported files
• Commands
  • dump-vars (to log)
  • message (to log)
  • include raw or crude files (with variable parsing and replacing)
  • Execute an external command and insert its output
• Conditional parsing based on variables
• redefine markup tags
• Log Filter
• Anchor command (for headers)
• Import CSV-file as table

Usage

aswsg [IN-FILE:]sourcefile [VARIABLE:value] > file.html

Checkout the example.

Control

Messages

Which messages will be logged, respectively not logged, can be controlled through the variable ASWSG-MESSAGE-FILTER. Messages with severity in ASWSG-MESSAGE-FILTER will not be sent to stderr.

Formatting

Description of the markup formatting.

You can use the mentioned variables to redefine the characters used for a formatting.

Line level formatting

Used at begin the beginning line, using one of the characters. Some characters are can be cascaded.

Function	Default Char	Variable	Example
Defining a variable	@	ASWSG-DEFINE	@variablename:value
Include a file oder files by pattern	+	ASWSG-INCLUDE	+filename or +file_patern
Raw (html) line to be inserted	$	ASWSG-RAWLINE	$<article>
Escape for a paragraph char	\	ASWSG-ESCAPE	\* this is no bullet list
Paragraph	(none)	(none)	Any text not starting not with a line level special. Empty lines start a new paragraph.
Header. The number of header characters define the depth of the header.	= or !	ASWSG-HEADER	== header level 2
Bullet list	* or -	ASWSG-LIST	* Bulltes and numbered Lists may be nested.
Numbered list	any off #0123456789	ASWSG-NUMERATION	2# a level 2 indented list element
Cite	>	ASWSG-CITE	> To be or not to be.
Single line command, optionally closed by an ")", should not be changed	(	ASWSG-COMMAND	(command parameter ...)
Defining a Table. The table character starts a new cell. One trailing pipe will be removed.	|	ASWSG-TABLE	|a 2 cell|table
Gemini style link	=>	ASWSG-GEMINI-LINK	=> http://haniarani.com/ Hania Rani
Comment	;	ASWSG-COMMENT	; this is a comment

To continue a long line (i.e. a long header split over two lines) add an \ to the end of the first line.

Inline formatting

Used to format text within a line, using 2 or 3 strings for begin, end and middle when needed.

Function	Default Char	Variables	Example
Variable replacing	{{...}}	ASWSG-VAR-1...ASWSG-VAR-2	{{variablename}}
Bold	*...*	ASWSG-BOLD-1...ASWSG-BOLD-2	*bold text*
Emphasised	//...//	ASWSG-EMP-1...ASWSG-EMP-2	//italic text//
Code	``...``	ASWSG-CODE-1...ASWSG-CODE-2	``text``
Strike through	~~...~~	ASWSG-STRIKE-1...ASWSG-STRIKE-2	~~text~~
Underline	__...__	ASWSG-UNDERL-1...ASWSG-UNDERL-2	__text__
Link-1 (internal)	[[...|...]]	ASWSG-LINK-1-1...ASWSG-LINK-1-3...ASWSG-LINK-1-2	[[text|URL]]
Link-2 (with rel=external)	[...](...)	ASWSG-LINK-2-1...ASWSG-LINK-2-3...ASWSG-LINK-2-2	[text](URL)
Link-3 (Link Index, to be inserted with commnd (LINK-INDEX))	[[...]]	ASWSG-LINK-3-1...ASWSG-LINK-1-2	[[URL]]

Glitches

There is a glitch when using the default markdown for emphasised // and a HTML link, which usually contains also two dashes, in one line. There is a small fix to avoid, that // will be used as the start of emphasised text, when there is a : in front of it, but that prevents any later rendering of emphasised in this line.

A good and easy solution in this case is to redefine emphasised. This could be done like this, to use two $-signs instead:

@ASWSG-EMP-1:$$
@ASWSG-EMP-2:$$

Multi-Line/Block formatting

A line just containing at least three characters to enter a special block. The block ends with the same characters in a line or a new block formatting.

Function	Default Char	Variable	Example
Citation	>	ASWSG-ML-CITE	>>>
Raw Lines	$	ASWSG-ML-RAW	$$$
Preformatted (code)	%	ASWSG-ML-CODE	%%%
Comment	;	ASWSG-ML-COM	;;;
Horizontal line (just one line)	-	ASWSG-LINE	----

Commands

All commands start with the ASWSG-COMMAND character which default is (.

Function	Form
Comment that will not be in the output HTML file	COMMENT any text
Dump variables to log	DUMP-VARS parameters ignored
Write a message to the log	MESSAGE any text
Set a link anchor with name	ANCHOR anchor-name
Insert link index for Link-3 of write it to [<file>]	LINK-INDEX filename
Include file raw without variable substitution	INCLUDE-FILE-RAW filename
Include file crude without variable substitution	INCLUDE-FILE-CRUDE filename
Include the output of a script/command (no variable substitution)	INCLUDE-SCRIPT programm parameters
Include CSV-file as table	INCLUDE-CSV filename.csv
Use the line formatter > as <blockquote> instead off <cite>. Activate this with the parameter "TRUE", "T" or no parameter. Every other parameter will be interpreted as false. (Default is cite.)	GT-AS-BLOCKQUOTE

Conditional commands

If a condition is set the following lines are only parsed if the condition criteria are true. This is valid until a new condition is set, a COND-ELSE or COND-END clause changes this. There is only one condition valid at a time. There is no nesting, a new COND-IF-... just changes the condition.

All conditions start with the ASWSG-COMMAND character which default is (.

Function	Form
Check if Variable is set	COND-IF-SET variable-name
Check if Variable is not set	COND-IF-NOT-SET variable-name
Check if Variable has the value	COND-IF-EQUAL variable-name value...
Check if Variable has not the value	COND-IF-NOT-EQUAL variable-name value...
Condition else case (last condition inverted)	COND-ELSE
End condition validation	COND-END

More Variables

Control Variables

Function	Name:Default
Number of header lines when parsing a table.	ASWSG-TABLE-HEADERLINES:1
Alignment of colons when parsing a table. L=left, C=center, R=right. If the value is to short, or unkown it defaults to L.	ASWSG-TABLE-ALIGNMENT:LL
CSV field separator	ASWSG-CSV-COMMA:;
CSV comment line	ASWSG-CSV-COMMENT:#
Automatically generate anchors for headers, T = true, everything else is false	ASWSG-AUTO-GENERATE-ANCHOR:T
Reverse Order of included files, T = true, everything else is false	ASWSG-INCLUDE-REVERSE:F
Date format	DATEFORMAT:2006-01-02
Time format	TIMEFORMAT:15:04:05
Timestamp format	TIMESTAMPFORMAT:2006-01-02 15:04:05 UTC+ 07:00
Filter out message types, default is "Dd" for debug messages	ASWSG-MESSAGE-FILTER:Dd
Use Gemini style links =>,T = true, everything else is false	GEMINI-LINK

The date and time format refers to GO's Time.Format.

Info Variables

Function	Name
Name of the file currently parsed	FILENAME
Name of the main file	IN-FILE
Current date	TODAY
Current time	TIME
Current timestamp (date + time)	NOW
The ASWSG version	ASWSG-VERSION
The ASWSG authors name	ASWSG-AUTHOR
The ASWSG license	ASWSG-LICENSE

Example

(comment next line defines a variable title)
@title:Test Page

+include filename

== A Header {{title}}

* This is
* just a simple List
*- with four entries
*- in two levels

# A numbered list
1 can be made with the numbers 0-9
1 for your convenience
21 but if you use two digits
22 it will be handeled like a nested list
5## numbers and # sign can be mixed
1 numbers don't have to be in sequence

| a table | with two columns
| and two | rows

$<! a raw line></body></html>

Parsing Logic

• Start (main)
  • setDefaultSiteVars
  • parseAndSetCommandLineVars
  • parseFile, for each line
    • process continued lines
    • parseLine
      • replaceInlineVars
      • parseCondition
      • validateCondition (return if not fulfilled)
      • block mode comment (return if true)
      • block mode code (return if true)
      • block mode crude (return if true)
      • block mode cite (continue) (TODO)
      • empty Line (new paragraph state)
      • ignore comment line
      • parseAndSetVar (return if true)
      • parseCommands (return if true)
      • parse raw lines (return if true)
      • process includes (parseFile, return if true)
      • parse gemini link (return if true)
      • parse header (return if true)
      • parseTableLine
      • parse horizontal line
      • parseCommonParagraphControls and regular text lines
        • parse LIST, CITE and NUMERATION
        • parse escaped line
        • parse paragraph / empty line
        • surroundWithHTMLTag for list, cite, numeration
        • parseInLine for
          • bold, emphasised, strike, code, link(1-3)