thezipcreator.srht.site

Artick

Created 11/21/2024, 2:00:37 PM

Artick is a static site generator that takes in a format somewhat similar to S-Expressions, and outputs either HTML or Gemtext. It is written in TypeScript, and it can be downloaded here.

Table of Contents

1. Usage

Artick may be invoked by running 
./run <format> <input directory> <output directory>
Where <format> is either html or gmi.
Input files (anything with the .artick file extension) will be taken from <input directory>, compiled, and placed in <output directory>. Other files (excluding format-specific files* ) are copied as well.

2. Syntax

Pages in Artick consist of tags. A tag begins with a left brace ({). After the left brace comes the tag type, which is then separated from the tag content by whitespace. The tag is ended by a right brace (}). An example of a tag is: 
{title My Page}
This is a tag with the name title and the content My Page.
Tags may span multiple lines: 
{content
	Lorem ipsum dolor sit amet, 
	consectetur adipiscing elit.
}
Tags may be nested: 
{list
	{item Foo}
	{item Bar}
	{item Baz}
}
The tag type determines what will display in the tag, depending on the current context. The default context is the Root Context.
Comments start with a hash (#), and may only occur at the beginning of a line: 
# This is a comment,
But # this is not. That # will display as normal text.
Any character may be escaped by placing a backslash (\) before it: 
\# This is not a comment
and \{this is not a tag\}
Single newlines are not significant, but double newlines create line breaks: 
There is no line break
between these lines.

But there is a line break

between these ones.
If a pipe (|) is used at the start of a line, then the entire rest of the line is copied as-is. This is useful for source code: 
{highlight js
	|if(x == 3) {
	|	console.log("Hello, World!");
	|}
}

3. Groups

Each page may be assigned a number of groups (via the groups tag). Groups are categories pages fall in; if you have a few pages about cats, for example, you might assign them all a Cat group.
Each group used generates a page at /groups/<name>. The content of the page may be customized by creating a page there in your input directory. Note that the names of input group pages may be different from the name of the group: the page name is all lowercase, and spaces are replaced with dashes. So the page for the group Things And Stuff will be at the page /groups/things-and-stuff.artick.

4. Configuration

A file named config.json may be placed in the input directory. This file determines various things about your site: 
{
	/// Site name
	siteName: string;
	/// Root of the site
	siteRoot: string;
	/// Font families to use
	fontFamilies: string[];
	/// Font families to use for monospace tags
	monospaceFontFamilies: string[];
	/// Custom fonts to provide (font family -> filename)
	fonts: {[family: string]: string};
	/// Width of the site content (css size specifier)
	width: string;
	colors: {
		/// Background color (css color)
		background: string;
		/// Content background color (css color)
		contentBackground: string;
		/// Content border color (css color)
		border: string;
		/// Title color (css color)
		title: string;
		/// Text color (css color)
		text: string;
		/// Alternate text color (css color)
		alternateText: string;
		/// Link color (css color)
		link: string;
		/// Hover link color (css color)
		hoverLink: string;
		/// Quote color
		quote: string;
	}
	/// An extra CSS file to run @include on
	extraCSS: string | null;
	/// Date info
	date: {
		/// Timezone to use for the date
		timezone: string;
		/// Locale to use for the date
		locale: string;
	},
	/// How to do bold/italic for formats that don't support it directly
	/// decoration - Put characters around it (as specified in `decoration`)
	/// sans - Use sans serif unicode characters
	/// serif - Use serif unicode characters
	decorationType: "decoration" | "sans" | "serif";
	/// Text decoration when enabled
	decoration: {
		italic: string;
		bold: string;
		code: string;
	}
	/// Highlighting config (kind -> color)
	highlight: { [kind: string]: string };
	/// custom syntax highlighting languages (language name -> filename)
	/// See speed-highlight-js's documentation for format.
	customSyntax: { [language: string]: string };
	/// Tab width
	tabWidth: string;
}
All config options are optional.

5. Tags

5.1. Root Context

The Root Context is the primary context every Artick source file starts in.

5.1.1. title

Sets the title of the page. This is displayed at the top of the page, used to fill in the <title> tag in HTML, and is used to reference the page in group pages: 
{title My Page}
Sets the title of the page to "My Page".

5.1.2. created

Sets the date created. Takes the UNIX Timestamp in milliseconds: 
{created 1732220321371}
Sets the date created to Thursday, November 21 2024 15:18:41 GMT-0500. An easy way to get this is to open a javascript REPL and run Date.now()

5.1.3. last-modified

Sets the date last modified, with the same format as created: 
{created 1732220321371}
Sets the date last modified to Thursday, November 21 2024 15:18:41 GMT-0500.

5.1.4. content

Opens the Content Context. This is where the main content of the page should be placed.

5.1.5. groups

Takes a comma separated list of groups, and sets the groups of the page to them: 
{groups Foo, Bar, Baz}
Sets the page's groups to Foo, Bar, and Baz.

5.1.6. references

Opens the References Context, which has a single tag: ref. This tag takes a name for the reference, and then arbitrary text after: 
{references
	{ref debt D. Graeber, Debt: the First 5,000 Years. Brooklyn, Ny: Melville House, 2011.}
	{ref anarchy P. Gelderloos, Anarchy works. 2015.}
}
Creates two references, one with name debt and one with name anarchy. The ref tag in the Content Context can be used in order to cite the works specified here.

5.2. Content Context

The context used within the context tag.

5.2.1. i

Renders italics: 
{i This is in italics!}
Will render as:
This is in italics!

5.2.2. b

Renders bold: 
{b This is in bold!}
Will render as:
This is in bold!

5.2.3. footnote

Adds a footnote to an article: 
This has a footnote.{footnote This is the footnote.}
Will add a footnote with the text "This is the footnote." to the article.

5.2.4. link

Creates a link; if there is more text after the link, that will be used instead of the link text: 
Explicit link: {link https://www.example.com/}

{link https://www.example.com Implicit link}
Will render as:
Explicit link: https://www.example.com/
Implicit link

5.2.5. line-link

Creates a link on its own line. This should be used instead of link whenever a line contains only the link; this is so the outputted Gemtext page will be more easily navigable. 
{line-link https://www.example.com/}
{line-link https://www.example.com Implicit link}
Will render as: ⇒ https://www.example.com/ ⇒ Implicit link

5.2.6. ref

Takes a reference name, and generates the citation number for that reference: 
Temples in ancient mesopotamia were large industrial operations.{ref debt}

5.2.7. section

Creates a new section, and opens the Section Context. The Section Context is the same as the Content Context, except with the addition of the title tag, which sets the title of the section. Sections may be nested: 
{section
	{title My Section}
	This is a section!
	{section
		{title My Subsection}
		This is a section within that section.
	}
}
Will generate a section named "My Section" with a subsection named "My Subsection".

5.2.8. pre

Creates preformatted text; useful in combination with |: 
{pre
	|This is
	|  pre
	|     for
	|        matted
}
Renders as: 
This is
  pre
     for
        matted

5.2.9. code

Used for inline code: 
The field {code foo} is a member of the class {code Bar}.
Renders as:
The field foo is a member of the class Bar.

5.2.10. highlight

Highlights text, using Speed Highlight JS. All languages supported by that library are supported to be used with this tag, with the addition of the artick language. The language is specified before the code, and is separated from it with whitespace: 
 {highlight c
 	|#include <stdio.h>
 	|
 	|int main(int argc, char **argv) {
 	|	printf("Hello, World!\n");
 	|	return 0;
 	|}
 }
Renders as: 
#include <stdio.h>

int main(int argc, char **argv) {
	printf("Hello, World!\n");
	return 0;
}

5.2.11. list

Creates a list, and opens the List Context, which is identical to the context it is placed in except with the addition of the item tag, which creates a list item: 
{list
	{item Foo}
	{item Bar}
	{item Baz}
}
Renders as:

5.2.12. format

Takes a format (either html or gmi) separated from the content by whitespace. The content will only render if the given format is the current format: 
The current format is: {format html HTML}{format gmi Gemtext}.
Will render "The current format is HTML." if the page is exported to HTML, and "The current format is Gemtext." if the page is exported to GMI.

5.2.13. image

Takes an image link, followed by a caption: 
{image /assets/channel_icon.png My Channel Icon}
Renders as:
My Channel Icon

My Channel Icon

5.2.14. quote

Renders a quote: 
{quote
	That's one small step for man, one giant leap for mankind.

	{i - Neil Armstrong}
}
Will render as:

That's one small step for man, one giant leap for mankind.
- Neil Armstrong

5.2.15. rule

Places a horizontal rule: 
{rule}
Will render as:

Footnotes

* For HTML, .gmi is exluded. For GMI, .html, .css, and .js are excluded.


Groups: Projects