Created 11/21/2024, 2:00:37 PM; Last modified 11/10/2025, 6:53:48 PM
*Artick* is a static site generator that takes in a format somewhat similar to S-Expressions, and outputs either HTML, Gemtext, Plaintext, or Wikitext.* 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`
+ 5.2.16. `table`
+ 5.3. Global Context
+ 5.3.1. `macro`
+ 5.3.2. `eval`
+ 5.3.3. `id`
+ 6. RSS
+ 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.
*Warning*: Artick text has the ability to run arbitrary unsandboxed Javascript code. Do not run it on text you do not trust!
/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:
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;
/// Link to the site (used for RSS)
siteLink: string;
/// Description of the site (used for RSS)
siteDescription: 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:
Sets the title of the page to "My Page".
5.1.2. `created`
Sets the date created. Takes the UNIX Timestamp[b] in milliseconds:
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:
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:
Renders as:
/This is in italics!/
5.2.2. `b`
Renders bold:
Renders as:
*This is in bold!*
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}
Renders 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}
Renders 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:
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:
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}.
Renders "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}
}
Renders as:
That's one small step for man, one giant leap for mankind.
/- Neil Armstrong/
5.2.15. `rule`
Places a horizontal rule:
Renders as:
~~~
5.2.16. `table`
Creates a table. The following subtags are used to insert content into the table:
- `column` - Defines a column
- `row` - Defines a row
- `item` - Defines an item (i.e. cell)
- `topleft` - Defines the top-left cell
And the `alt` tag can be used to set a title for the table.
For example:
{table
{alt Addition table}
{column 1} {column 2} {column 3}
{row 1} {row 2} {row 3}
{topleft +}
{item 2} {item 3} {item 4}
{item 3} {item 4} {item 5}
{item 4} {item 5} {item 6}
}
Renders as: ```Addition table
┌─┬┬┬─┬─┐
│+├┼┤2│3│
├┬┼┴┼─┼─┤
├┼┤2│3│4│
├┴┼─┼─┼─┤
│2│3│4│5│
├─┼─┼─┼─┤
│3│4│5│6│
└─┴─┴─┴─┘
A table may have no rows or items defined, and both `topleft` and `alt` may be absent. However, it must have at least one column.
## 5.3. Global Context
The global context contains tags that are available in all other contexts.
### 5.3.1. `macro`
Defines a new tag (called a /macro tag/) that expands to user-defined text. Macros may take /arguments/ which may appear in the expanded text via the `arg` tag. The macro name and its arguments are placed directly in the macro, separated by spaces, and the expanded text is placed inside a `value` tag. For example:
{macro apples-oranges apples oranges
{value I have {arg apples} apples and {arg oranges} oranges.}
}
Creates a macro that takes two arguments. If we invoke it via:
{apples-oranges 2 3}
We will get the text:
I have 2 apples and 3 oranges.
The final argument of a macro will contain all other text present in the tag, so for example:
{apples-oranges 2 three {i hundred} and {b one}}
will expand to:
I have 2 apples and three/hundred/ and *one* oranges.
Macros may also specify a context in which they should be evaluated. By default, they are evaluated in the same context that the macro is used in. This can be done with the `context` tag:
{macro set-title title
{context root}
{value {title {arg title}}}
}
This macro will always use the root context's `title` tag when called, even if it's used within `content` or `section`.
The only allowed contexts are `root` and `content`.
### 5.3.2. `eval`
Evaluates javascript code inside an `async` IIFE‡. This function's return value is then converted to a string and parsed as Artick code, then inserted into the document.
For example:
{eval return "foo".replace("f", "b")}
results in:
boo
### 5.3.3. `id`
Returns its input exactly. This is occasionally useful for macro writing.
# 6. RSS
All groups will automatically have an RSS[e] feed generated at `groups/<group name>-rss.xml`. This includes the "all" group, so if you want to link to an RSS feed containing all pages, link to `groups/all-rss.xml`.
In addition, groups automatically have an RSS link appended to the end, and pages automatically receive a <link> tag that directs RSS readers to feeds corresponding to the groups of the page[f].
# Footnotes
* * The point of the Wikitext format is for exporting to a wiki outside of a generated site. As such, a few features (such as groups) are not supported.
* † For HTML, `.gmi` is exluded. For GMI, `.html`, `.css`, and `.js` are excluded. For Wikitext, nothing is excluded.
* ‡ Immediately invoked function expression
# Links
=> https://git.sr.ht/~thezipcreator/artick [a] https://git.sr.ht/~thezipcreator/artick
=> https://en.wikipedia.org/wiki/Unix_time [b] https://en.wikipedia.org/wiki/Unix_time
=> https://www.example.com [c] https://www.example.com
=> https://deno.land/x/speed_highlight_js [d] https://deno.land/x/speed_highlight_js
=> https://en.wikipedia.org/wiki/RSS [e] https://en.wikipedia.org/wiki/RSS
=> https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel#alternate [f] https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel#alternate
# Groups
=> /groups/software.gmi Software
Mastodon
