131 lines
No EOL
8.7 KiB
HTML
131 lines
No EOL
8.7 KiB
HTML
<!doctype html>
|
||
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Scriptorium User's Guide · Scriptorium Blog</title><link href="/scriptorium_blog/css/normalize.css" rel="stylesheet"><link href="/scriptorium_blog/css/magick.css" rel="stylesheet"><link href="/scriptorium_blog/css/custom.css" rel="stylesheet"><link href="/scriptorium_blog/feed" rel="alternate" type="application/atom+xml"><link rel="me" href="https://social.ahlcode.fi/@nicd"><meta name="author" content="Mikko Ahlroth"><meta name="description" content><meta itemprop="name" content="Scriptorium User's Guide"><meta itemprop="author" content="Mikko Ahlroth"><meta itemprop="headline" content="Scriptorium User's Guide"><meta itemprop="description" content><meta name="twitter:card" content="summary_large_image"><meta name="twitter:site" content><meta name="twitter:title" content="Scriptorium User's Guide"><meta name="twitter:description" content><meta name="twitter:creator" content><meta property="og:title" content="Scriptorium User's Guide"><meta property="og:type" content="article"><meta property="og:description" content><meta property="og:site_name" content="Scriptorium Blog"><meta property="og:url" content="https://nicd.gitlab.io/scriptorium_blog/guide"></head><body><header id="title" role="banner"><h1><a href="/scriptorium_blog/index.html">Scriptorium Blog</a></h1><nav><ul><li><a href="https://hex.pm/packages/scriptorium">Hex</a></li><li><a href="https://hexdocs.pm/scriptorium">HexDocs</a></li><li><a href="https://gitlab.com/Nicd/scriptorium">GitLab</a></li><li><a href="/scriptorium_blog/guide.html">User's Guide</a></li><li><a href="https://gitlab.com/Nicd/scriptorium_blog">This blog's source</a></li></ul></nav></header><main><article class="page"><header><h2>Scriptorium User's Guide</h2></header><div><p><em>This user's guide is a work-in-progress. Please keep checking back for more information. If you have
|
||
any questions or feedback, don't hesitate to ask me <a href="https://social.ahlcode.fi/@nicd">on the fediverse</a>
|
||
or on the Gleam Discord (user Nicd).</em></p>
|
||
<h3>Table of Contents</h3>
|
||
<ol>
|
||
<li><a href="#installation">Prerequisites & Installation</a></li>
|
||
<li><a href="#filesystem">Default Filesystem Layout</a></li>
|
||
<li><a href="#writing">Writing a Post</a></li>
|
||
</ol>
|
||
<h3><a name="installation"></a>Prerequisites & Installation</h3>
|
||
<p>Scriptorium requires the following software:</p>
|
||
<ul>
|
||
<li>Gleam 1.1+</li>
|
||
<li>Node.js (tested on version 20)</li>
|
||
</ul>
|
||
<p>In addition, you will need at least a preliminary understanding of the Gleam language. The default blog
|
||
setup does not require any special knowledge, but customizing the generation process will require
|
||
writing Gleam code.</p>
|
||
<p>Typically creating a blog with Scriptorium requires creating a new Gleam project. When you have a Gleam
|
||
project, you can add the library as a dependency by using <kbd>gleam add scriptorium</kbd>.</p>
|
||
<p>To set up a basic blog, replace the project's main file with the following:</p>
|
||
<pre><code class="language-gleam">import gleam/result
|
||
import gleam/option
|
||
import gleam/io
|
||
import scriptorium/builder
|
||
import scriptorium/config.{type Configuration}
|
||
import scriptorium/defaults
|
||
|
||
pub fn main() {
|
||
let config =
|
||
defaults.default_config(
|
||
"My Blog",
|
||
"https://my.blog.example/",
|
||
"en",
|
||
config.Author(
|
||
"Person McPerson",
|
||
option.Some("person@example.com"),
|
||
option.Some("https://fedi.instance.example/@person"),
|
||
),
|
||
"© Person McPerson",
|
||
)
|
||
|
||
io.debug(build(config))
|
||
}
|
||
|
||
pub fn build(config: Configuration) {
|
||
// Parse the files
|
||
use db <- result.try(builder.parse(config))
|
||
// Compile Markdown into HTML
|
||
let compiled = builder.compile(db, config)
|
||
// Render content into Lustre elements
|
||
let rendered = builder.render(db, compiled, config)
|
||
// Write rendered content into the filesystem
|
||
builder.write(rendered, config)
|
||
}
|
||
</code></pre>
|
||
<p>This is the minimum setup for building a blog. Now the blog can be generated with <kbd>gleam run</kbd>.</p>
|
||
<h3><a name="filesystem"></a>Default Filesystem Layout</h3>
|
||
<p>By default the blog generator expects the following folders to exist:</p>
|
||
<ul>
|
||
<li><code>data</code> – Master folder for input data, inside the root of the project folder.<ul>
|
||
<li><code>posts</code> – Folder for posts.</li>
|
||
<li><code>pages</code> – Folder for pages.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>As an illustrative example of the contents, the filesystem contents of this blog at the time of writing
|
||
were:</p>
|
||
<pre><code>data
|
||
├── menu
|
||
├── pages
|
||
│ ├── 404.md
|
||
│ └── guide.md
|
||
└── posts
|
||
├── 2024-04-14-hello-world.md
|
||
└── 2024-04-21-scriptorium-published.md
|
||
</code></pre>
|
||
<!-- TODO: Screen reader alternative for the above? -->
|
||
|
||
<h3><a name="writing"></a>Writing a Post</h3>
|
||
<h4>Post Filename</h4>
|
||
<p>To write a post, create a new file in the <code>./data/posts</code> folder. The filename must consist of the
|
||
following:</p>
|
||
<ul>
|
||
<li>an <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> formatted date, i.e. <code>YYYY-MM-DD</code>,</li>
|
||
<li>a dash,</li>
|
||
<li>an <em>optional</em> zero-padded 2-digit order number used for ordering when two posts were written on the
|
||
same day and don't have time information, followed by a dash,</li>
|
||
<li>a <em>slug</em> that is a free-form name for the post used in the post filename and thus the final URL, and</li>
|
||
<li>the file extension <code>.md</code>.</li>
|
||
</ul>
|
||
<p>Note that because the slug is used in the filename and in the URL, it should only contain filename and
|
||
URL safe text. The recommendation is to stick to regular characters, dashes, and underscores, without
|
||
any spaces. "Regular characters" here does not exclude non-latin characters, as they are safely
|
||
percent-encoded in a URL.</p>
|
||
<h4>Post Contents</h4>
|
||
<p>Scriptorium posts are written in <a href="https://en.wikipedia.org/wiki/Markdown">Markdown</a>.
|
||
<a href="https://marked.js.org">Marked.js</a> is used for compiling Markdown, so its documentation should be
|
||
consulted when there is a question about how something is rendered.</p>
|
||
<h5>Header</h5>
|
||
<p>There are, however, some special parts at the start of a post. Let's look at an example:</p>
|
||
<pre><code class="language-markdown">Post Title
|
||
tag1, tag2, tag3
|
||
time: 21:15 Europe/Helsinki
|
||
description: Example post
|
||
image: https://example.com/example.jpg
|
||
|
||
Hello, and welcome to this example post!
|
||
</code></pre>
|
||
<p>The first line in a file is the post title. After that, optionally, come post tags on their own line,
|
||
separated by a comma. Post tags are used as-is, so they also should contain only filename and URL safe
|
||
content, and no spaces.</p>
|
||
<p>After the tags are <em>headers</em>. Headers are a collection of key-value pairs, separated by a colon. They
|
||
can contain various metadata about the post, and the user can implement their own headers by
|
||
customizing the post view. There are some predefined headers:</p>
|
||
<ul>
|
||
<li><code>time</code> – Defines the time when the post was written. The format is <kbd>hh:mm TZ</kbd>, where the
|
||
first part is the local time using a 24 hour clock, and the second is the
|
||
<a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">local timezone identifier</a>.</li>
|
||
<li><code>description</code> – A description of the post that is used for link embeds on external services.</li>
|
||
<li><code>image</code> – An image that is used for link embeds on external services. Should be on the smaller side
|
||
and must be an absolute URL.</li>
|
||
</ul>
|
||
<h5>Splitting</h5>
|
||
<p>Often it is not sensible to show the whole post in list views with many posts. In this case the post
|
||
can be divided into two pieces. In the list view, only the first part is shown, and in the individual
|
||
post page, both parts are shown.</p>
|
||
<p>To do this, insert <kbd><!-- SPLIT --></kbd> in the post. It's recommended to put this on its
|
||
own line and not inside any HTML or Markdown content that would get broken when split apart.</p>
|
||
</div></article></main><section id="sidebar"><nav id="tags" aria-label="Tags"><ul><li><a href="/scriptorium_blog/tag/hex.html" style="font-size:100%;">hex</a></li><li><a href="/scriptorium_blog/tag/i18n.html" style="font-size:100%;">i18n</a></li></ul></nav><nav id="archives" aria-label="Archives"><ul><li><a href="/scriptorium_blog/archive/2024.html">2024</a><ul><li><a href="/scriptorium_blog/archive/2024/06.html">June (1)</a></li><li><a href="/scriptorium_blog/archive/2024/04.html">April (2)</a></li></ul></li></ul></nav></section><footer><p>© Mikko Ahlroth · Powered by: <a href="https://gleam.run/">Gleam</a>, <a href="https://hexdocs.pm/lustre">Lustre</a>, <a href="https://gitlab.com/Nicd/scriptorium">Scriptorium</a></p></footer></body></html> |