clayoven - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #go #android #linux #docker #java #awesome #cli #kubernetes #pytorch #ios

clayoven

(★ 332)

💎 beautiful website generator aimed at math-heavy sites

File Explorer

Download Latest Version (.zip)

- - clayoven.yml
  - codeql.yml
- ltex.dictionary.en-US.txt
- ltex.disabledRules.en-US.txt
- ltex.hiddenFalsePositives.en-US.txt
- clayoven.png
- clayoven.svg
- syntax-demo.png
- clayoven
- - settings.json
  - tasks.json
- - rouge.sass
  - script.js
  - style.sass
  - template.slim
- - .gitkeep
- - mathjax.mjs
  - minify.mjs
  - xypic.js
- .gitignore
- .yarnrc.yml
- 404.index.clay
- index.clay
- package.json
- scratch.index.clay
- test.svg
- yarn.lock
- - claytext.rb
  - config.rb
  - git.rb
  - httpd.rb
  - init.rb
  - toplevel.rb
  - transforms.rb
  - util.rb
- helper.rb
- init_test.rb
- production_test.rb
- unit_test.rb
.gitignore
.mailmap
.rubocop.yml
.simplecov
Gemfile
Gemfile.lock
LICENSE
Rakefile
README.md

# Installation Guide

1. Get the code

git clone https://github.com/artagnon/clayoven

Downloads the entire project code from GitHub to your computer.

cd clayoven

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

.yarn/ # provided by `init`

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

3. Ruby

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Ruby Ruby is required to use the bundle command.

bundle install

Installs the Ruby libraries listed in the Gemfile.

✅ If bundle install finishes without errors, continue with the run command from the README (e.g. rails server).

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# clayoven ![logo](https://raw.githubusercontent.com/artagnon/clayoven/master/assets/clayoven.png)

clayoven is a beautiful static site generator with a carefully curated set of features. It has been built at a glacial pace, over a [decade](https://github.com/artagnon/clayoven/commit/d4d40161e9f76dbe74078c669de9af698cf621d6), as [my website](https://artagnon.com) expanded in content. I have a spread of mathematical notes, both typeset and handwritten, software-related posts with code, and some wider-audience articles; it is good on all three fronts. The source files are written in "claytext", a custom format built for elegance and speed.

rdoc documentation is available [here](http://artagnon.github.io/clayoven/).

## Unique features

- Small! ~700 lines of well-written and well-documented Ruby.
- Beautiful and easily extensible markup, with a dedicated vscode plugin for it.
- Automatically picks timestamps from git history, respecting moves.
- Server-side rendering of math, including commutative diagrams, via MathJaX and XyJaX.

## Demo

A starter project is bundled with the following `scratch.index.clay`:

![syntax highlighting demo](https://user-images.githubusercontent.com/37226/113478818-91a7f280-948b-11eb-87f0-3610f2aa3160.png)

whose rendered output can be seen [here](https://artagnon.com/scratch).

Here's an excerpt of embedded MathJaX with IntelliSense powered by vsclay:

![IntelliSense demo](https://user-images.githubusercontent.com/37226/113474233-24866400-946f-11eb-8e72-b82460d16c71.mp4)

## Getting started

There is no published gem. To get started, clone, run `bundle` to install the required gems, and put `bin/clayoven` in `$PATH`. Then, run `clayoven init` in a fresh directory. To start writing, install [vsclay](https://marketplace.visualstudio.com/items?itemName=artagnon.vsclay) for vscode, which will provide the necessary syntax highlighting, IntelliSense support for MathJaX, and trigger-[incremental build]-on-save functionality.

## The site-generation engine

All site content is split up into "topics", to put in the sidebar, each of which can either serve as an index to a collection of `ContentPages` (as a bunch of `.clay` files in a subdirectory with the name `#{topic}`), or a single `IndexPage` (named `#{topic}.index.clay`). `index.clay` is special-cased to serve as the root of the site.

So, if you have these files,

.clayoven/              # provided by `init`
    .vscode/                # provided by `init`
    .yarn/                  # provided by `init`
    lib/                    # provided by `init`
    design/                 # provided by `init`
    dist/                   # provided by `init`
    index.clay              # provided by `init`
    scratch.index.clay      # provided by `init`
    404.index.clay          # provided by `init`
    feed.xml                # provided by `init`
    sitemap.xml             # provided by `init`
    blog.index.clay
    blog/personal/1.clay
    blog/math/1.clay
    colophon.index.clay

clayoven automatically builds a sidebar with `index`, `blog` and `colophon` (each of which are instances of `IndexPage`). `/blog` will have links to the posts `/blog/personal/1` and `/blog/math/1` (each of which are instances of `ContentPage`), under the titles `personal` and `math` (the "subtopics"). If there are multiple `ContentPage` entries under an `IndexPage`, the latter simply serves to give a introduction, with links to articles automatically appearing after the introduction. `IndexPage` and `ContentPage` are run through the same `design/template.slim`, and the template file has access to the accessors.

The engine works closely with the git object store, and builds are incremental by default; it mostly Just Works, and when it doesn't, there's an option to force a full rebuild. The engine also pulls out the created-timestamp (`Page#crdate`) and last-modified-timestamp (`Page#lastmod`) from git, respecting moves. `ContentPages` are sorted by `crdate`, reverse-chronologically, and `IndexPages` are sorted alphabetically.

## Usage

- `clayoven init` to generate the necessary starter project.
- `clayoven` to generate HTML files incrementally based on the current git index.
- `clayoven aggressive` to regenerate the entire site; only requires to be run on occassion.
- `clayoven httpd` to preview your website locally.

## Configuration

0. `.clayoven/author` is the author of the site: used in RSS feed.
1. `.clayoven/sitename` is URL of the site, excluding the `https://` prefix.
2. `.clayoven/hidden` is a list of `IndexFiles` that should be built, but not displayed in the sidebar. You would want to use it for your 404 page and drafts.
3. `.clayoven/tz` is a timezone-to-location mapper, with lines of the form `+0000 London`. clayoven digs through the git history for locations, and exposes a `Page#locations`.
4. `.clayoven/subtopic` is a [subtopic directory]-to-subtitle mapper, with lines of the form `inf ∞-categories`.

## The claytext processor

The claytext processor is, at its core, a paragraph-processor; all content must be split up into either plain paragraphs, or "fences" (multiple paragraphs delimited by start and end tokens). The function of most markers should be evident from the `scratch.html` produced by a `clayoven init`. The format is strict, and the processor doesn't like files with paragraphs wrapped using hard line breaks.

`Clayoven::Claytext::Transforms::LINE` matches paragraphs where all lines begin with some regex, and `Clayoven::Claytext::Transforms::Fenced` match fences (could be multiple paragraphs) that start and end with the specified tokens. In addition to this, there are inline markdown markers `` `...` `` and `[...](...)`, for content that is to be put in `<mark>` and `<a>`, respectively.

## Tips

- Check in the generated HTML to the site's repository, so that eyeballing `git diff` can serve as a testing mechanism.
- If you accidentally commit `.clay` files before running clayoven, running it afterward will do nothing, since it will see a clean git index; you'll need to run the aggressive variant.
- Importing historical content is easy; a `git commit --date="#{historical_date}"` would give the post an appropriate creation date that will be respected in the sorting-order.

## Planned features, and anti-features

- Get vsclay to report syntax errors.
- Anti: extend clayoven in ways that would necessitate an ugly implementation.