💾 Archived View for thezipcreator.srht.site › projects › artick.gmi captured on 2024-12-17 at 10:20:56. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
Created 11/21/2024, 2:00:37 PM
[ 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.
The Root Context is the primary context every Artick source file starts in.
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".
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()`
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.
Opens the Content Context. This is where the main content of the page should be placed.
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`.
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.
The context used within the `context` tag.
Renders italics:
{i This is in italics!}
Will render as:
/This is in italics!/
Renders bold:
{b This is in bold!}
Will render as:
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.
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]
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:
Takes a reference name, and generates the citation number for that reference:
Temples in ancient mesopotamia were large industrial operations.{ref debt}
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".
Creates preformatted text; useful in combination with `|`:
{pre
|This is
| pre
| for
| matted
}
Renders as:
This is
pre
for
matted
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`.
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;
}
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}.
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.
Takes an image link, followed by a caption:
{image /assets/channel_icon.png My Channel Icon}
Renders as:
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/
Places a horizontal rule:
{rule}
Will render as:
~~~
[a] https://git.sr.ht/~thezipcreator/artick
[b] https://en.wikipedia.org/wiki/Unix_time
[d] https://deno.land/x/speed_highlight_js