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.[a]

[ Table of Contents ]

  + 1. Usage
  + 2. Syntax
  + 3. Groups
  + 4. Configuration
  + 5. Tags
    + 5.1. Root Context
      + 5.1.1. `title`
      + 5.1.2. `created`
      + 5.1.3. `last-modified`
      + 5.1.4. `content`
      + 5.1.5. `groups`
      + 5.1.6. `references`
    + 5.2. Content Context
      + 5.2.1. `i`
      + 5.2.2. `b`
      + 5.2.3. `footnote`
      + 5.2.4. `link`
      + 5.2.5. `line-link`
      + 5.2.6. `ref`
      + 5.2.7. `section`
      + 5.2.8. `pre`
      + 5.2.9. `code`
      + 5.2.10. `highlight`
      + 5.2.11. `list`
      + 5.2.12. `format`
      + 5.2.13. `image`
      + 5.2.14. `quote`
      + 5.2.15. `rule`
  + Footnotes
  + Links

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.

/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!");
	|}
}

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`.

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.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[b] 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`:

{last-modified 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[c]

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.[d] 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:

• Foo
• Bar
• Baz

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

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:

~~~

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

[a] https://git.sr.ht/~thezipcreator/artick

[b] https://en.wikipedia.org/wiki/Unix_time

[c] https://www.example.com

[d] https://deno.land/x/speed_highlight_js

Projects